1<chapter id=reference> 2 <title>Reference</title> 3 4 <sect1 id=obtaining xreflabel="Obtaining DejaGnu"> 5 <title>Obtaining DejaGnu</title> 6 7 <para>You can obtain DejaGnu from the DejaGnu web site at the 8 <ulink URL="http://www.gnu.org">Free Software Foundation</ulink>, 9 which is at <ulink 10 URL="http://www.gnu.org/software/dejagnu/">www.gnu.org/software/dejagnu/ 11 </ulink></para> 12 13 </sect1> 14 15 <sect1 id=installation xreflabel="Installation"> 16 <title>Installation</title> 17 18 <para>Once you have the DejaGnu source unpacked and available, you must 19 first configure the software to specify where it is to run (and the 20 associated defaults); then you can proceed to installing it.</para> 21 22 <sect2 id=configuring xreflabel="Configuring DejaGnu"> 23 <title>Configuring DejaGnu</title> 24 25 <para>It is usually best to configure in a directory separate from the 26 source tree, specifying where to find the source with the optional 27 <emphasis>--srcdir</emphasis> option to 28 <emphasis>configure</emphasis>. DejaGnu uses the GNU 29 <emphasis>autoconf</emphasis> to configure itself. For more info on using 30 autoconf, read the GNU autoconf manual. To configure, execute the 31 <filename>configure</filename> program, no other options are 32 required. For an example, to configure in a seperate tree for objects, 33 execute the configure script from the source tree like this:</para> 34 35 <screen> 36 ../dejagnu-&version/configure 37 </screen> 38 39 <para>DejaGnu doesn't care at config time if it's for testing a native 40 system or a cross system. That is determined at runtime by using the 41 config files.</para> 42 43 <para>You may also want to use the <command>configure</command> option 44 <emphasis>--prefix</emphasis> to specify where you want DejaGnu and its 45 supporting code installed. By default, installation is in subdirectories 46 of <filename>/usr/local</filename>, but you can select any alternate 47 directory <symbol>altdir</symbol> by including 48 <option>--prefix</option>{altdir}} on the 49 <command>configure</command> command line. (This value is captured in 50 the Makefile variables <emphasis>prefix</emphasis> and 51 <emphasis>exec</emphasis>prefix}.)</para> 52 53 <para>Save for a small number of example tests, the DejaGnu distribution 54 itself does not include any testsuites; these are available 55 separately. Testsuites for the GNU development tools are included in 56 those releases. After configuring the top-level DejaGnu directory, unpack 57 and configure the test directories for the tools you want to test; then, 58 in each test directory, run <emphasis>make check</emphasis> to build 59 auxiliary programs required by some of the tests, and run the test 60 suites.</para> 61 62 </sect2> 63 64 <sect2 id=installing xreflabel="Installing DejaGnu"> 65 <title>Installing DejaGnu</title> 66 67 <para>To install DejaGnu in your filesystem (either in 68 <filename>/usr/local</filename>, or as specified by your 69 <emphasis>--prefix</emphasis> option to <emphasis>configure</emphasis>), 70 execute.</para> 71 72 <screen> 73 eg$ make install 74 </screen> 75 76 <para><emphasis>make install</emphasis>does thes things for 77 DejaGnu:</para> 78 79 <itemizedlist mark=bullet> 80 <listitem><para>Look in the path specified for executables 81 <symbol>$exec_prefix</symbol>) for directories called 82 <filename>lib</filename> and <filename>bin</filename>. If these 83 directories do not exist, <emphasis>make install</emphasis> creates 84 them.</para></listitem> 85 86 <listitem><para>Create another directory in the 87 <filename>share</filename> directory, called 88 <filename>dejagnu</filename>, and copy all the library files into 89 it.</para></listitem> 90 91 <listitem><para>Create a directory in the 92 <filename>dejagnu/share</filename> directory, called 93 <filename>config</filename>, and copy all the configuration files into 94 it.</para></listitem> 95 96 <listitem><para>Copy the <emphasis>runtest</emphasis> shell script into 97 <filename>$exec_prefix/bin</filename>.</para></listitem> 98 99 <listitem><para>Copy <filename>runtest.exp</filename> into 100 <filename>$exec_prefix/lib/dejagnu</filename>. This is the main Tcl 101 code implementing DejaGnu.</para></listitem> 102 103 </itemizedlist> 104 </sect2> 105 </sect1> 106 107 <sect1 id=builtins xreflabel="Builtin Procedures"> 108 <title>Builtin Procedures</title> 109 110 <para>DejaGnu provides these Tcl procedures.</para> 111 112 <sect2 id=coreprocs xreflabel="Core Internal Procedures"> 113 <title>Core Internal Procedures</title> 114 115 <sect3 id=mailfile xreflabel="mail_file procedure"> 116 <title>Mail_file Procedure</title> 117 118 <funcsynopsis role="tcl"> 119 <funcdef><function>mail_file</function></funcdef> 120 <paramdef><parameter>file to subject</parameter</paramdef> 121 </funcsynopsis> 122 <variablelist> 123 <varlistentry> 124 <term><parameter></parameter></term> 125 <listitem><para></para></listitem> 126 </varlistentry> 127 </variablelist> 128 </sect3> 129 130 <sect3 id=openlogs xreflabel="open_logs procedure"> 131 <title>Open_logs Procedure</title> 132 133 <para></para> 134 135 <funcsynopsis role="tcl"> 136 <funcdef><function>open_logs</function></funcdef> 137 <paramdef><parameter></parameter</paramdef> 138 </funcsynopsis> 139 </sect3> 140 141 <sect3 id=closelogs xreflabel="close_logs procedure"> 142 <title>Close_logs Procedure</title> 143 144 <para></para> 145 146 <funcsynopsis role="tcl"> 147 <funcdef><function>close_logs</function></funcdef> 148 <paramdef><parameter></parameter</paramdef> 149 </funcsynopsis> 150 </sect3> 151 152 <sect3 id=isbuild xreflabel="isbuild procedure"> 153 <title>Isbuild Procedure</title> 154 155 <para>Tests for a particular build host environment. If the 156 currently configured host matches the argument string, the result is 157 <emphasis>1</emphasis>; otherwise the result is 158 <emphasis>0</emphasis>. <emphasis>host</emphasis> must be a full 159 three-part configure host name; in particular, you may not use the 160 shorter nicknames supported by configure (but you can use wildcard 161 characters, using shell syntax, to specify sets of names). If it is 162 passed a NULL string, then it returns the name of the build canonical 163 configuration.</para> 164 165 <funcsynopsis role="tcl"> 166 <funcdef><function>isbuild</function></funcdef> 167 <paramdef><parameter>pattern</parameter</paramdef> 168 </funcsynopsis> 169 <variablelist> 170 <varlistentry> 171 <term><parameter>pattern</parameter></term> 172 <listitem><para></para></listitem> 173 </varlistentry> 174 </variablelist> 175 </sect3> 176 177 <sect3 id=isremote xreflabel="is_remote procedure"> 178 <title>Is_remote Procedure</title> 179 180 <para></para> 181 182 <funcsynopsis role="tcl"> 183 <funcdef><function>is_remote</function></funcdef> 184 <paramdef><parameter>board</parameter</paramdef> 185 </funcsynopsis> 186 <variablelist> 187 <varlistentry> 188 <term><parameter></parameter></term> 189 <listitem><para></para></listitem> 190 </varlistentry> 191 </variablelist> 192 </sect3> 193 194 <sect3 id=is3way xreflabel="is3way procedure"> 195 <title>is3way Procedure</title> 196 197 <para>Tests for a canadian cross. This is when the tests will be run 198 on a remotly hosted cross compiler. If it is a canadian cross, then 199 the result is <emphasis>1</emphasis>; otherwise the result is 200 <emphasis>0</emphasis>.</para> 201 202 <funcsynopsis role="tcl"> 203 <funcdef><function>is3way</function></funcdef> 204 <paramdef><parameter></parameter</paramdef> 205 </funcsynopsis> 206 </sect3> 207 208 <sect3 id=ishost xreflabel="ishost procedure"> 209 <title>Ishost Procedure</title> 210 211 <para>Tests for a particular host environment. If the currently 212 configured host matches the argument string, the result is 213 <emphasis>1</emphasis>; otherwise the result is 214 <emphasis>0</emphasis>. <emphasis>host</emphasis> must be a full 215 three-part configure host name; in particular, you may not use the 216 shorter nicknames supported by configure (but you can use wildcard 217 characters, using shell syntax, to specify sets of names).</para> 218 219 <funcsynopsis role="tcl"> 220 <funcdef><function>ishost</function></funcdef> 221 <paramdef><parameter>pattern</parameter></paramdef> 222 </funcsynopsis> 223 <variablelist> 224 <varlistentry> 225 <term><parameter></parameter></term> 226 <listitem><para></para></listitem> 227 </varlistentry> 228 </variablelist> 229 </sect3> 230 231 <sect3 id=istarget xreflabel="istarget procedure"> 232 <title>Istarget Procedure</title> 233 234 <para>Tests for a particular target environment. If the currently 235 configured target matches the argument string, the result is 236 <emphasis>1</emphasis> ; otherwise the result is 237 <emphasis>0</emphasis>. target must be a full three-part configure 238 target name; in particular, you may not use the shorter nicknames 239 supported by configure (but you can use wildcard characters, using 240 shell syntax, to specify sets of names). If it is passed a 241 <emphasis>NULL</emphasis> string, then it returns the name of the 242 build canonical configuration.</para> 243 244 <funcsynopsis role="tcl"> 245 <funcdef><function>istarget</function></funcdef> 246 <paramdef><parameter>args</parameter></paramdef> 247 </funcsynopsis> 248 <variablelist> 249 <varlistentry> 250 <term><parameter></parameter></term> 251 <listitem><para></para></listitem> 252 </varlistentry> 253 </variablelist> 254 </sect3> 255 256 <sect3 id=isnative xreflabel="isnative procedure"> 257 <title>Isnative Procedure</title> 258 259 <para>Tests whether the current configuration has the same host and 260 target. When it runs in a native configuration this procedure returns 261 a <emphasis>1</emphasis>; otherwise it returns a 262 <emphasis>0</emphasis>.</para> 263 264 <funcsynopsis role="tcl"> 265 <funcdef><function>isnative</function></funcdef> 266 <paramdef><parameter></parameter</paramdef> 267 </funcsynopsis> 268 </sect3> 269 270 <sect3 id=unknown xreflabel="unknown procedure"> 271 <title>Unknown Procedure</title> 272 273 <para></para> 274 275 <funcsynopsis role="tcl"> 276 <funcdef><function>unknown</function></funcdef> 277 <paramdef><parameter>args</parameter></paramdef> 278 </funcsynopsis> 279 <variablelist> 280 <varlistentry> 281 <term><parameter>args</parameter></term> 282 <listitem><para></para></listitem> 283 </varlistentry> 284 </variablelist> 285 </sect3> 286 287 <sect3 id=cloneoutput xreflabel="clone_output procedure"> 288 <title>Clone_output Procedure</title> 289 290 <para></para> 291 292 <funcsynopsis role="tcl"> 293 <funcdef><function>clone_output</function></funcdef> 294 <paramdef><parameter>message</parameter></paramdef> 295 </funcsynopsis> 296 <variablelist> 297 <varlistentry> 298 <term><parameter>message</parameter></term> 299 <listitem><para></para></listitem> 300 </varlistentry> 301 </variablelist> 302 </sect3> 303 304 <sect3 id=resetvars xreflabel="reset_vars procedure"> 305 <title>Reset_vars Procedure</title> 306 307 <para></para> 308 309 <funcsynopsis role="tcl"> 310 <funcdef><function>reset_vars</function></funcdef> 311 <paramdef><parameter></parameter</paramdef> 312 </funcsynopsis> 313 </sect3> 314 315 <sect3 id=logandexit xreflabel="log_and_exit procedure"> 316 <title>Log_and_exit Procedure</title> 317 318 <para></para> 319 320 <funcsynopsis role="tcl"> 321 <funcdef><function>log_and_exit</function></funcdef> 322 <paramdef><parameter></parameter</paramdef> 323 </funcsynopsis> 324 </sect3> 325 326 <sect3 id=logsummary xreflabel="log_summary procedure"> 327 <title>Log_summary Procedure</title> 328 329 <para></para> 330 331 <funcsynopsis role="tcl"> 332 <funcdef><function>log_summary</function></funcdef> 333 <paramdef><parameter>args</parameter</paramdef> 334 </funcsynopsis> 335 <variablelist> 336 <varlistentry> 337 <term><parameter>args</parameter></term> 338 <listitem><para></para></listitem> 339 </varlistentry> 340 </variablelist> 341 </sect3> 342 343 <sect3 id=cleanup xreflabel="cleanup procedure"> 344 <title>Cleanup Procedure</title> 345 346 <para></para> 347 348 <funcsynopsis role="tcl"> 349 <funcdef><function>cleanup</function></funcdef> 350 <paramdef><parameter></parameter</paramdef> 351 </funcsynopsis> 352 </sect3> 353 354 <sect3 id=setupxfail xreflabel="setup_xfail procedure"> 355 <title>Setup_xfail Procedure</title> 356 357 <para>Declares that the test is expected to fail on a particular set 358 of configurations. The config argument must be a list of full 359 three-part configure target name; in particular, you may not use the 360 shorter nicknames supported by configure (but you can use the common 361 shell wildcard characters to specify sets of names). The 362 <emphasis>bugid</emphasis> argument is optional, and used only in the 363 logging file output; use it as a link to a bug-tracking system such 364 as <productname>GNATS</productname>.</para> 365 366 <para>Once you use <function>setup_xfail</function>, the 367 <function>fail</function> and <function>pass</function> procedures 368 produce the messages <emphasis>XFAIL</emphasis> and 369 <emphasis>XPASS</emphasis> respectively, allowing you to distinguish 370 expected failures (and unexpected success!) from other test 371 outcomes.</para> 372 373 <warning><para>Warning you must clear the expected failure after 374 using setup_xfail in a test case. Any call to <function>pass 375 </function>or <function>fail</function>l clears the expected failure 376 implicitly; if the test has some other outcome, e.g. an error, you 377 can call <function>clear_xfail</function> to clear the expected 378 failure explicitly. Otherwise, the expected-failure declaration 379 applies to whatever test runs next, leading to surprising 380 results.</para></warning> 381 382 <funcsynopsis role="tcl"> 383 <funcdef><function>setup_xfail</function></funcdef> 384 <paramdef><parameter>config</parameter> 385 <parameter>bugid</parameter></paramdef> 386 </funcsynopsis> 387 <variablelist> 388 <varlistentry> 389 <term><parameter>config</parameter></term> 390 <listitem><para>The config triplet to trigger whether this is an 391 unexpected or expect failure.</para></listitem> 392 </varlistentry> 393 <varlistentry> 394 <term><parameter>bugid</parameter></term> 395 <listitem><para>The optional bugid, used to tie it this test case 396 to a bug tracking system.</para></listitem> 397 </varlistentry> 398 </variablelist> 399 </sect3> 400 401 <sect3 id=recordtest xreflabel="record_test procedure"> 402 <title>Record_test Procedure</title> 403 404 <para></para> 405 406 <funcsynopsis role="tcl"> 407 <funcdef><function>record_test</function></funcdef> 408 <paramdef><parameter>type</parameter> 409 <parameter>message</parameter> 410 <parameter>args</parameter></paramdef> 411 </funcsynopsis> 412 <variablelist> 413 <varlistentry> 414 <term><parameter>type</parameter></term> 415 <listitem><para></para></listitem> 416 </varlistentry> 417 <varlistentry> 418 <term><parameter>message</parameter></term> 419 <listitem><para></para></listitem> 420 </varlistentry> 421 <varlistentry> 422 <term><parameter>args</parameter></term> 423 <listitem><para></para></listitem> 424 </varlistentry> 425 </variablelist> 426 </sect3> 427 428 <sect3 id=pass xreflabel="pass procedure"> 429 <title>Pass Procedure</title> 430 431 <para>Declares a test to have passed. <function>pass</function> 432 writes in the log files a message beginning with 433 <emphasis>PASS</emphasis> (or <emphasis>XPASS</emphasis>, if failure 434 was expected), appending the argument 435 <parameter>string</parameter>.</para> 436 437 <funcsynopsis role="tcl"> 438 <funcdef><function>pass</function></funcdef> 439 <paramdef><parameter>string</parameter></paramdef> 440 </funcsynopsis> 441 <variablelist> 442 <varlistentry> 443 <term><parameter>string</parameter></term> 444 <listitem><para>The string to use for this PASS 445 message.</para></listitem> 446 </varlistentry> 447 </variablelist> 448 </sect3> 449 450 <sect3 id=fail xreflabel="fail procedure"> 451 <title>Fail Procedure</title> 452 453 <para>Declares a test to have failed. <function>fail</function> 454 writes in the log files a message beginning with 455 <emphasis>FAIL</emphasis> (or <emphasis>XFAIL</emphasis>, if failure 456 was expected), appending the argument 457 <parameter>string</parameter>.</para> 458 459 <funcsynopsis role="tcl"> 460 <funcdef><function>fail</function></funcdef> 461 <paramdef><parameter>string</parameter></paramdef> 462 </funcsynopsis> 463 <variablelist> 464 <varlistentry> 465 <term><parameter>string</parameter></term> 466 <listitem><para>The string to use for this FAIL 467 message.</para></listitem> 468 </varlistentry> 469 </variablelist> 470 </sect3> 471 472 <sect3 id=xpass xreflabel="xpass procedure"> 473 <title>Xpass Procedure</title> 474 475 <para>Declares a test to have unexpectably passed, when it was 476 expected to be a failure. <function>xpass</function> 477 writes in the log files a message beginning with 478 <emphasis>XPASS</emphasis> (or <emphasis>XFAIL</emphasis>, if failure 479 was expected), appending the argument 480 <parameter>string</parameter>.</para> 481 482 <funcsynopsis role="tcl"> 483 <funcdef><function>xpass</function></funcdef> 484 <paramdef><parameter>string</parameter></paramdef> 485 </funcsynopsis> 486 <variablelist> 487 <varlistentry> 488 <term><parameter>string</parameter></term> 489 <listitem><para>The string to use for this output 490 state.</para></listitem> 491 </varlistentry> 492 </variablelist> 493 </sect3> 494 495 <sect3 id=xfail xreflabel="xfail procedure"> 496 <title>Xfail Procedure</title> 497 498 <para>Declares a test to have expectably 499 failed. <function>xfail</function> 500 writes in the log files a message beginning with 501 <emphasis>XFAIL</emphasis> (or <emphasis>PASS</emphasis>, if success 502 was expected), appending the argument 503 <parameter>string</parameter>.</para> 504 505 <funcsynopsis role="tcl"> 506 <funcdef><function>xpass</function></funcdef> 507 <paramdef><parameter>string</parameter></paramdef> 508 </funcsynopsis> 509 <variablelist> 510 <varlistentry> 511 <term><parameter>string</parameter></term> 512 <listitem><para>The string to use for this output 513 state.</para></listitem> 514 </varlistentry> 515 </variablelist> 516 </sect3> 517 518 <sect3 id=setwarningthreshold xreflabel="set_warning_threshold procedure"> 519 <title>Set_warning_threshold Procedure</title> 520 521 <para>Sets the value of <symbol>warning_threshold</symbol>. A value 522 of <emphasis>0</emphasis> disables it: calls to 523 <function>warning</function> will not turn a 524 <emphasis>PASS</emphasis> or <emphasis>FAIL</emphasis> into an 525 <emphasis>UNRESOLVED</emphasis>.</para> 526 527 <funcsynopsis role="tcl"> 528 <funcdef><function>set_warning_threshold</function></funcdef> 529 <paramdef><parameter>threshold</parameter></paramdef> 530 </funcsynopsis> 531 <variablelist> 532 <varlistentry> 533 <term><parameter>threshold</parameter></term> 534 <listitem><para>This is the value of the new warning 535 threshold.</para></listitem> 536 </varlistentry> 537 </variablelist> 538 </sect3> 539 540 <sect3 id=getwarningthreshold xreflabel="get_warning_threshold procedure"> 541 <title>Get_warning_threshold Procedure</title> 542 543 <para>Returns the current value of 544 <symbol>{warning_threshold</symbol>. The default value is 3. This 545 value controls how many <function>warning</function> procedures can 546 be called before becoming <emphasis>UNRESOLVED</emphasis>.</para> 547 548 <funcsynopsis role="tcl"> 549 <funcdef><function>get_warning_threshold</function></funcdef> 550 <paramdef><parameter></parameter></paramdef> 551 </funcsynopsis> 552 553 </sect3> 554 <sect3 id=warning xreflabel="warning procedure"> 555 <title>Warning Procedure</title> 556 557 <para>Declares detection of a minor error in the test case 558 itself. <function>warning</function> writes in the log files a message 559 beginning with <emphasis>WARNING</emphasis>, appending the argument 560 <parameter>string</parameter>. Use <function>warning</function> rather 561 than <function>perror</function> for cases (such as communication 562 failure to be followed by a retry) where the test case can recover from 563 the error. If the optional <parameter>number</parameter> is supplied, 564 then this is used to set the internal count of warnings to that 565 value.</para> 566 567 <para>As a side effect, <symbol>warning_threshold</symbol> or more 568 calls to warning in a single test case also changes the effect of the 569 next <function>pass</function> or <function>fail</function> command: 570 the test outcome becomes <emphasis>UNRESOLVED</emphasis> since an 571 automatic <emphasis>PASS</emphasis> or <emphasis>FAIL</emphasis> may 572 not be trustworthy after many warnings. If the optional numeric value 573 is <emphasis>0</emphasis>, then there are no further side effects to 574 calling this function, and the following test outcome doesn't become 575 <emphasis>UNRESOLVED</emphasis>. This can be used for errors with no 576 known side effects.</para> 577 578 <funcsynopsis role="tcl"> 579 <funcdef><function>warning</function></funcdef> 580 <paramdef><parameter>string</parameter> 581 <parameter>number</parameter> 582 </paramdef> 583 </funcsynopsis> 584 <variablelist> 585 <varlistentry> 586 <term><parameter>string</parameter></term> 587 <listitem><para></para></listitem> 588 </varlistentry> 589 <varlistentry> 590 <term><parameter>number</parameter></term> 591 <listitem><para>The optional number to set the error counter. Thius 592 is only used to fake out the counter when using the 593 <function>xfail</function> procedure to control when it flips the 594 output over to <emphasis>UNRESOLVED</emphasis> 595 state.</para></listitem> 596 </varlistentry> 597 </variablelist> 598 599 </sect3> 600 <sect3 id=perror xreflabel="perror procedure"> 601 <title>Perror Procedure</title> 602 603 <para>Declares a severe error in the testing framework 604 itself. <function>perror</function> writes in the log files a message 605 beginning with <emphasis>ERROR</emphasis>, appending the argument 606 <parameter>string</parameter>.</para> 607 608 <para>As a side effect, perror also changes the effect of the next 609 <function>pass</function> or <function>fail</function> command: the 610 test outcome becomes <emphasis>UNRESOLVED</emphasis>, since an 611 automatic <emphasis>PASS</emphasis> or <emphasis>FAIL</emphasis> cannot 612 be trusted after a severe error in the test framework. If the optional 613 numeric value is <emphasis>0</emphasis>, then there are no further side 614 effects to calling this function, and the following test outcome 615 doesn't become <emphasis>UNRESOLVED</emphasis>. This can be used for 616 errors with no known side effects.</para> 617 618 <funcsynopsis role="tcl"> 619 <funcdef><function>perror</function></funcdef> 620 <paramdef><parameter>string</parameter> 621 <parameter>number</parameter> 622 </paramdef> 623 </funcsynopsis> 624 <variablelist> 625 <varlistentry> 626 <term><parameter>string</parameter></term> 627 <listitem><para></para></listitem> 628 </varlistentry> 629 <varlistentry> 630 <term><parameter>number</parameter></term> 631 <listitem><para>The optional number to set the error counter. Thius 632 is only used to fake out the counter when using the 633 <function>xfail</function> procedure to control when it flips the 634 output over to <emphasis>UNRESOLVED</emphasis> 635 state.</para></listitem> 636 </varlistentry> 637 </variablelist> 638 639 </sect3> 640 <sect3 id=note xreflabel="note procedure"> 641 <title>Note Procedure</title> 642 643 <para>Appends an informational message to the log 644 file. <function>note</function> writes in the log files a message 645 beginning with <emphasis>NOTE</emphasis>, appending the argument 646 <parameter>string</parameter>. Use <function>note</function> 647 sparingly. The <function>verbose</function> should be used for most 648 such messages, but in cases where a message is needed in the log file 649 regardless of the verbosity level use <function>note</function>.</para> 650 651 <funcsynopsis role="tcl"> 652 <funcdef><function>note</function></funcdef> 653 <paramdef><parameter>string</parameter></paramdef> 654 </funcsynopsis> 655 <variablelist> 656 <varlistentry> 657 <term><parameter>string</parameter></term> 658 <listitem><para>The string to use for this note.</para></listitem> 659 </varlistentry> 660 </variablelist> 661 </sect3> 662 663 <sect3 id=untested xreflabel="untested procedure"> 664 <title>Untested Procedure</title> 665 666 <para>Declares a test was not run. <function>untested</function> writes 667 in the log file a message beginning with <emphasis>UNTESTED</emphasis>, 668 appending the argument <emphasis>string</emphasis>. For example, you 669 might use this in a dummy test whose only role is to record that a test 670 does not yet exist for some feature.</para> 671 672 <funcsynopsis role="tcl"> 673 <funcdef><function>untested</function></funcdef> 674 <paramdef><parameter>string</parameter></paramdef> 675 </funcsynopsis> 676 <variablelist> 677 <varlistentry> 678 <term><parameter>string</parameter></term> 679 <listitem><para>The string to use for this output 680 state.</para></listitem> 681 </varlistentry> 682 </variablelist> 683 </sect3> 684 685 <sect3 id=unresolved xreflabel="unresolved procedure"> 686 <title>Unresolved Procedure</title> 687 688 <para>Declares a test to have an unresolved 689 outcome. <function>unresolved</function> writes in the log file a 690 message beginning with <emphasis>UNRESOLVED</emphasis>, appending the 691 argument <emphasis>string</emphasis>. This usually means the test did 692 not execute as expected, and a human being must go over results to 693 determine if it passed or failed (and to improve the test case).</para> 694 695 <funcsynopsis role="tcl"> 696 <funcdef><function>unresolved</function></funcdef> 697 <paramdef><parameter>string</parameter></paramdef> 698 </funcsynopsis> 699 <variablelist> 700 <varlistentry> 701 <term><parameter>string</parameter></term> 702 <listitem><para>The string to use for this output 703 state.</para></listitem> 704 </varlistentry> 705 </variablelist> 706 </sect3> 707 708 <sect3 id=unsupported xreflabel="unsupported procedure"> 709 <title>Unsupported Procedure</title> 710 711 <para>Declares that a test case depends on some facility that does not 712 exist in the testing environment. <function>unsupported</function> 713 writes in the log file a message beginning with 714 <emphasis>UNSUPPORTED</emphasis>, appending the argument string.</para> 715 716 <funcsynopsis role="tcl"> 717 <funcdef><function>unsupported</function></funcdef> 718 <paramdef><parameter>string</parameter></paramdef> 719 </funcsynopsis> 720 <variablelist> 721 <varlistentry> 722 <term><parameter>string</parameter></term> 723 <listitem><para>The string to use for this output 724 state.</para></listitem> 725 </varlistentry> 726 </variablelist> 727 </sect3> 728 729 <sect3 id=inittestcounts xreflabel="init_testcounts procedure"> 730 <title>Init_testcounts Procedure</title> 731 732 <para></para> 733 734 <funcsynopsis role="tcl"> 735 <funcdef><function>init_testcounts</function></funcdef> 736 <paramdef><parameter></parameter></paramdef> 737 </funcsynopsis> 738 </sect3> 739 740 <sect3 id=incrcount xreflabel="incr_count procedure"> 741 <title>Incr_count Procedure</title> 742 743 <para></para> 744 745 <funcsynopsis role="tcl"> 746 <funcdef><function>incr_count</function></funcdef> 747 <paramdef><parameter>name</parameter> 748 <parameter>args</parameter></paramdef> 749 </funcsynopsis> 750 <variablelist> 751 <varlistentry> 752 <term><parameter>name</parameter></term> 753 <listitem><para></para></listitem> 754 </varlistentry> 755 <varlistentry> 756 <term><parameter>args</parameter></term> 757 <listitem><para></para></listitem> 758 </varlistentry> 759 </variablelist> 760 </sect3> 761 762 <sect3 id=transform xreflabel="transform procedure"> 763 <title>transform Procedure</title> 764 765 <para>Generates a string for the name of a tool as it was configured 766 and installed, given its native name (as the argument 767 <parameter>toolname</parameter>). This makes the assumption that all 768 tools are installed using the same naming conventions: For example, 769 for a cross compiler supporting the <emphasis>m68k-vxworks</emphasis> 770 configuration, the result of transform <command>gcc</command> is 771 <command>m68k-vxworks-gcc</command>.</para> 772 773 <funcsynopsis role="tcl"> 774 <funcdef><function>transform</function></funcdef> 775 <paramdef><parameter>toolname</parameter></paramdef> 776 </funcsynopsis> 777 <variablelist> 778 <varlistentry> 779 <term><parameter>toolname</parameter></term> 780 <listitem><para>The name of the cross-development program to 781 transform.</para></listitem> 782 </varlistentry> 783 </variablelist> 784 </sect3> 785 786 787 <sect3 id=checkconditionalxfail xreflabel="check_conditional_xfail procedure"> 788 <title>Check_conditional_xfail Procedure</title> 789 790 <para>This procedure adds a conditional xfail, based on compiler 791 options used to create a test case executable. If an include options 792 is found in the compiler flags, and it's the right architecture, 793 it'll trigger an <emphasis>XFAIL</emphasis>. Otherwise it'll produce 794 an ordinary <emphasis>FAIL</emphasis>. You can also specify flags to 795 exclude. This makes a result be a <emphasis>FAIL</emphasis>, even if 796 the included options are found. To set the conditional, set 797 the variable <symbol>compiler_conditional_xfail_data</symbol> to the 798 fields <programlisting>"[message string] [targets list] [includes 799 list] [excludes list]"</programlisting> (descriptions below). This is 800 the checked at pass/fail decision time, so there is no need to call 801 the procedure yourself, unless you wish to know if it gets 802 triggered. After a pass/fail, the variable is reset, so it doesn't 803 effect other tests. It returns <emphasis>1</emphasis> if the 804 conditional is true, or <emphasis>0</emphasis> if the conditional is 805 false.</para> 806 807 <funcsynopsis role="tcl"> 808 <funcdef><function>check_conditional_xfail</function></funcdef> 809 <paramdef><parameter>message</parameter> 810 <parameter>targets</parameter> 811 <parameter>includes</parameter> 812 <parameter>excludes</parameter></paramdef> 813 </funcsynopsis> 814 <variablelist> 815 <varlistentry> 816 <term><parameter>message</parameter></term> 817 <listitem><para>This is the message to print with the normal test 818 result.</para></listitem> 819 </varlistentry> 820 <varlistentry> 821 <term><parameter>targets</parameter></term> 822 <listitem><para>This is a string with the list targets to activate 823 this conditional on.</para></listitem> 824 </varlistentry> 825 <varlistentry> 826 <term><parameter>includes</parameter></term> 827 <listitem><para>This is a list of sets of options to search for in 828 the compiler options to activate this conditional. If the list of 829 sets of options is empty or if any set of the options matches, 830 then this conditional is true. (It may be useful to specify an 831 empty list of include sets if the conditional is always true 832 unless one of the exclude sets matches.)</para></listitem> 833 </varlistentry> 834 <varlistentry> 835 <term><parameter>excludes</parameter></term> 836 <listitem><para>This is a list of sets of options to search for in 837 the compiler options to activate this conditional. If any set of 838 the options matches, (regardless of whether any of the include sets 839 match) then this conditional is de-activated.</para></listitem> 840 </varlistentry> 841 </variablelist> 842 843 <example> 844 <title>Specifying the conditional xfail data</title> 845 846 <programlisting> 847 set compiler_conditional_xfail_data { \ 848 "I sure wish I knew why this was hosed" \ 849 "sparc*-sun*-* *-pc-*-*" \ 850 {"-Wall -v" "-O3"} \ 851 {"-O1" "-Map"} \ 852 } 853 </programlisting> 854 855 </example> 856 857 <para>What this does is it matches only for these two targets if 858 "-Wall -v" or "-O3" is set, but neither "-O1" or "-Map" is set. For 859 a set to match, the options specified are searched for independantly 860 of each other, so a "-Wall -v" matches either "-Wall -v" or "-v 861 -Wall". A space seperates the options in the string. Glob-style 862 regular expressions are also permitted.</para> 863 864 </sect3> 865 866 <sect3 id=clearxfail xreflabel="clear_xfail procedure"> 867 <title>Clear_xfail Procedure</title> 868 869 <para>Cancel an expected failure (previously declared with 870 <command>setup_xfail</command>) for a particular set of 871 configurations. The <parameter>config</parameter> argument is a list 872 of configuration target names. It is only necessary to call 873 <command>clear_xfail</command> if a test case ends without calling 874 either <command>pass</command> or <command>fail</command>, after 875 calling <command>setup_xfail</command>.</para> 876 877 <funcsynopsis role="tcl"> 878 <funcdef><function>clear_xfail</function></funcdef> 879 <paramdef><parameter>config</parameter></paramdef> 880 </funcsynopsis> 881 <variablelist> 882 <varlistentry> 883 <term><parameter>config</parameter></term> 884 <listitem><para>The configuration triplets to 885 clear.</para></listitem> 886 </varlistentry> 887 </variablelist> 888 </sect3> 889 890 <sect3 id=verbose xreflabel="verbose procedure"> 891 <title>Verbose Procedure</title> 892 893 <para>Test cases can use this function to issue helpful messages 894 depending on the number of <option>--verbose</option> options on the 895 runtest command line. It prints string if the value of the variable 896 <symbol>verbose</symbol> is higher than or equal to the optional 897 number. The default value for number is <emphasis>1</emphasis>. Use 898 the optional <option>-log</option> argument to cause string to always 899 be added to the log file, even if it won't be printed. Use the 900 optional <option>-x</option> argument to log the test results into 901 a parsable XML file. Use the optional <option>-n</option> argument 902 to print string without a trailing newline. Use the optional 903 <option>--</option> argument if string begins with "-".</para> 904 905 <funcsynopsis role="tcl"> 906 <funcdef><function>verbose</function></funcdef> 907 <paramdef><parameter>-log</parameter> 908 <parameter>-x</parameter> 909 <parameter>-n</parameter> 910 <parameter>-r</parameter> 911 <parameter>string</parameter> 912 <parameter>number</parameter></paramdef> 913 </funcsynopsis> 914 <variablelist> 915 <varlistentry> 916 <term><parameter>-x</parameter></term> 917 <listitem><para></para></listitem> 918 </varlistentry> 919 <varlistentry> 920 <term><parameter>-log</parameter></term> 921 <listitem><para></para></listitem> 922 </varlistentry> 923 <varlistentry> 924 <term><parameter>-n</parameter></term> 925 <listitem><para></para></listitem> 926 </varlistentry> 927 <varlistentry> 928 <term><parameter>--</parameter></term> 929 <listitem><para></para></listitem> 930 </varlistentry> 931 <varlistentry> 932 <term><parameter>string</parameter></term> 933 <listitem><para></para></listitem> 934 </varlistentry> 935 <varlistentry> 936 <term><parameter>number</parameter></term> 937 <listitem><para></para></listitem> 938 </varlistentry> 939 </variablelist> 940 </sect3> 941 942 <sect3 id=loadlib xreflabel="load_lib procedure"> 943 <title>Load_lib Procedure</title> 944 945 <para>Loads a DejaGnu library file by searching a fixed path built 946 into DejaGnu. If DejaGnu has been installed, it looks in a path 947 starting with the installed library directory. If you are running 948 DejaGnu directly from a source directory, without first running 949 <command>make install</command>, this path defaults to the current 950 directory. In either case, it then looks in the current directory 951 for a directory called <filename>lib</filename>. If there are 952 duplicate definitions, the last one loaded takes precedence over the 953 earlier ones.</para> 954 955 <funcsynopsis role="tcl"> 956 <funcdef><function>load_lib</function></funcdef> 957 <paramdef><parameter>filespec</parameter></paramdef> 958 </funcsynopsis> 959 <variablelist> 960 <varlistentry> 961 <term><parameter>filespec</parameter></term> 962 <listitem><para>The name of the DejaGnu library file to 963 load.</para></listitem> 964 </varlistentry> 965 </variablelist> 966 </sect3> 967 968 </sect2> 969 970 <sect2 id=remoteprocs> 971 <title>Procedures For Remote Communication</title> 972 973 <para><filename>lib/remote.exp</filename> defines these 974 functions, for establishing and managing communications. Each 975 of these procedures tries to establish the connection up to 976 three times before returning. Warnings (if retries will 977 continue) or errors (if the attempt is abandoned) report on 978 communication failures. The result for any of these 979 procedures is either <emphasis>-1</emphasis>, when the 980 connection cannot be established, or the spawn ID returned by 981 the <productname>Expect</productname> command 982 <command>spawn</command>.</para> 983 984 <para>It use the value of the <symbol>connect</symbol> field 985 in the <symbol>target_info</symbol> array (was 986 <symbol>connectmode</symbol> as the type of connection to 987 make. Current supported connection types are tip, kermit, 988 telnet, rsh, rlogin, and netdata. If the <option>--reboot</option> 989 option was used on the runtest command line, then the target 990 is rebooted before the connection is made.</para> 991 992 <sect3 id=callremote xreflabel="call_remote procedure"> 993 <title>Call_remote Procedure</title> 994 995 <para></para> 996 997 <funcsynopsis role="tcl"> 998 <funcdef><function>call_remote</function></funcdef> 999 <paramdef><parameter>type</parameter> 1000 <parameter>proc</parameter> 1001 <parameter>dest</parameter> 1002 <parameter>args</parameter></paramdef> 1003 </funcsynopsis> 1004 <variablelist> 1005 <varlistentry> 1006 <term><parameter>proc</parameter></term> 1007 <listitem><para></para></listitem> 1008 </varlistentry> 1009 <varlistentry> 1010 <term><parameter>dest</parameter></term> 1011 <listitem><para></para></listitem> 1012 </varlistentry> 1013 <varlistentry> 1014 <term><parameter>args</parameter></term> 1015 <listitem><para></para></listitem> 1016 </varlistentry> 1017 </variablelist> 1018 </sect3> 1019 1020 <sect3 id=checkforboardstatus xreflabel="check_for_board_status 1021 procedure"> 1022 <title>Check_for_board_status Procedure</title> 1023 1024 <para></para> 1025 1026 <funcsynopsis role="tcl"> 1027 <funcdef><function>check_for_board_status</function></funcdef> 1028 <paramdef><parameter>variable</parameter></paramdef> 1029 </funcsynopsis> 1030 <variablelist> 1031 <varlistentry> 1032 <term><parameter>variable</parameter></term> 1033 <listitem><para></para></listitem> 1034 </varlistentry> 1035 </variablelist> 1036 </sect3> 1037 1038 <sect3 id=fileonbuild xreflabel="file_on_build procedure"> 1039 <title>File_on_build Procedure</title> 1040 1041 <para></para> 1042 1043 <funcsynopsis role="tcl"> 1044 <funcdef><function>file_on_build</function></funcdef> 1045 <paramdef><parameter>op</parameter> 1046 <parameter>file</parameter> 1047 <parameter>args</parameter></paramdef> 1048 </funcsynopsis> 1049 <variablelist> 1050 <varlistentry> 1051 <term><parameter>op</parameter></term> 1052 <listitem><para></para></listitem> 1053 </varlistentry> 1054 <varlistentry> 1055 <term><parameter>file</parameter></term> 1056 <listitem><para></para></listitem> 1057 </varlistentry> 1058 <varlistentry> 1059 <term><parameter>args</parameter></term> 1060 <listitem><para></para></listitem> 1061 </varlistentry> 1062 </variablelist> 1063 </sect3> 1064 1065 <sect3 id=fileonhost xreflabel="file_on_host procedure"> 1066 <title>File_on_host Procedure</title> 1067 1068 <para></para> 1069 1070 <funcsynopsis role="tcl"> 1071 <funcdef><function>file_on_host</function></funcdef> 1072 <paramdef><parameter>op</parameter> 1073 <parameter>file</parameter> 1074 <parameter>args</parameter></paramdef> 1075 </funcsynopsis> 1076 <variablelist> 1077 <varlistentry> 1078 <term><parameter>op</parameter></term> 1079 <listitem><para></para></listitem> 1080 </varlistentry> 1081 <varlistentry> 1082 <term><parameter>file</parameter></term> 1083 <listitem><para></para></listitem> 1084 </varlistentry> 1085 <varlistentry> 1086 <term><parameter>args</parameter></term> 1087 <listitem><para></para></listitem> 1088 </varlistentry> 1089 </variablelist> 1090 </sect3> 1091 1092 <sect3 id=localexec xreflabel="local_exec procedure"> 1093 <title>Local_exec Procedure</title> 1094 1095 <para></para> 1096 1097 <funcsynopsis role="tcl"> 1098 <funcdef><function>local_exec</function></funcdef> 1099 <paramdef><parameter>commandline</parameter> 1100 <parameter>inp</parameter> 1101 <parameter>outp</parameter> 1102 <parameter>timeout</parameter></paramdef> 1103 </funcsynopsis> 1104 <variablelist> 1105 <varlistentry> 1106 <term><parameter>inp</parameter></term> 1107 <listitem><para></para></listitem> 1108 </varlistentry> 1109 <varlistentry> 1110 <term><parameter>outp</parameter></term> 1111 <listitem><para></para></listitem> 1112 </varlistentry> 1113 <varlistentry> 1114 <term><parameter>timeout</parameter></term> 1115 <listitem><para></para></listitem> 1116 </varlistentry> 1117 </variablelist> 1118 </sect3> 1119 1120 <sect3 id=remotebinary xreflabel="remote_binary procedure"> 1121 <title>Remote_binary Procedure</title> 1122 1123 <para></para> 1124 1125 <funcsynopsis role="tcl"> 1126 <funcdef><function>remote_binary</function></funcdef> 1127 <paramdef><parameter>host</parameter></paramdef> 1128 </funcsynopsis> 1129 <variablelist> 1130 <varlistentry> 1131 <term><parameter>host</parameter></term> 1132 <listitem><para></para></listitem> 1133 </varlistentry> 1134 </variablelist> 1135 </sect3> 1136 1137 <sect3 id=remoteclose xreflabel="remote_close procedure"> 1138 <title>Remote_close Procedure</title> 1139 1140 <para></para> 1141 1142 <funcsynopsis role="tcl"> 1143 <funcdef><function>remote_close</function></funcdef> 1144 <paramdef><parameter>shellid</parameter></paramdef> 1145 </funcsynopsis> 1146 <variablelist> 1147 <varlistentry> 1148 <term><parameter>shellid</parameter></term> 1149 <listitem><para>This is the value returned by a call 1150 to <function>remote_open</function>. This closes the 1151 connection to the target so resources can be used by 1152 others. This parameter can be left off if the 1153 <symbol>fileid</symbol> field in the 1154 <symbol>target_info</symbol> array is set.</para></listitem> 1155 </varlistentry> 1156 </variablelist> 1157 </sect3> 1158 1159 <sect3 id=remotedownload xreflabel="remote_download procedure"> 1160 <title>Remote_download Procedure</title> 1161 1162 <para></para> 1163 1164 <funcsynopsis role="tcl"> 1165 <funcdef><function>remote_download</function></funcdef> 1166 <paramdef><parameter>dest</parameter> 1167 <parameter>file</parameter> 1168 <parameter>args</parameter></paramdef> 1169 </funcsynopsis> 1170 <variablelist> 1171 <varlistentry> 1172 <term><parameter>dest</parameter></term> 1173 <listitem><para></para></listitem> 1174 </varlistentry> 1175 <varlistentry> 1176 <term><parameter>file</parameter></term> 1177 <listitem><para></para></listitem> 1178 </varlistentry> 1179 <varlistentry> 1180 <term><parameter>args</parameter></term> 1181 <listitem><para></para></listitem> 1182 </varlistentry> 1183 </variablelist> 1184 </sect3> 1185 1186 <sect3 id=remoteexec xreflabel="remote_exec procedure"> 1187 <title>Remote_exec Procedure</title> 1188 1189 <para></para> 1190 1191 <funcsynopsis role="tcl"> 1192 <funcdef><function>remote_exec</function></funcdef> 1193 <paramdef><parameter>hostname</parameter> 1194 <parameter>program</parameter> 1195 <parameter>args</parameter></paramdef> 1196 </funcsynopsis> 1197 <variablelist> 1198 <varlistentry> 1199 <term><parameter>hostname</parameter></term> 1200 <listitem><para></para></listitem> 1201 </varlistentry> 1202 <varlistentry> 1203 <term><parameter>program</parameter></term> 1204 <listitem><para></para></listitem> 1205 </varlistentry> 1206 <varlistentry> 1207 <term><parameter>args</parameter></term> 1208 <listitem><para></para></listitem> 1209 </varlistentry> 1210 </variablelist> 1211 </sect3> 1212 1213 <sect3 id=remoteexpect xreflabel="remote_expect procedure"> 1214 <title>Remote_expect Procedure</title> 1215 1216 <para></para> 1217 1218 <funcsynopsis role="tcl"> 1219 <funcdef><function>remote_expect</function></funcdef> 1220 <paramdef><parameter>board</parameter> 1221 <parameter>timeout</parameter> 1222 <parameter>args</parameter></paramdef> 1223 </funcsynopsis> 1224 <variablelist> 1225 <varlistentry> 1226 <term><parameter>board</parameter></term> 1227 <listitem><para></para></listitem> 1228 </varlistentry> 1229 <varlistentry> 1230 <term><parameter>timeout</parameter></term> 1231 <listitem><para></para></listitem> 1232 </varlistentry> 1233 <varlistentry> 1234 <term><parameter>args</parameter></term> 1235 <listitem><para></para></listitem> 1236 </varlistentry> 1237 </variablelist> 1238 </sect3> 1239 1240 <sect3 id=remotefile xreflabel="remote_file procedure"> 1241 <title>Remote_file Procedure</title> 1242 1243 <para></para> 1244 1245 <funcsynopsis role="tcl"> 1246 <funcdef><function>remote_file</function></funcdef> 1247 <paramdef><parameter>dest</parameter> 1248 <parameter>args</parameter</paramdef> 1249 </funcsynopsis> 1250 <variablelist> 1251 <varlistentry> 1252 <term><parameter>dest</parameter></term> 1253 <listitem><para></para></listitem> 1254 </varlistentry> 1255 <varlistentry> 1256 <term><parameter>args</parameter></term> 1257 <listitem><para></para></listitem> 1258 </varlistentry> 1259 </variablelist> 1260 </sect3> 1261 1262 <sect3 id=remoteld xreflabel="remote_ld procedure"> 1263 <title>Remote_ld Procedure</title> 1264 1265 <para></para> 1266 1267 <funcsynopsis role="tcl"> 1268 <funcdef><function>remote_ld</function></funcdef> 1269 <paramdef><parameter>dest</parameter> 1270 <parameter>prog</parameter></paramdef> 1271 </funcsynopsis> 1272 <variablelist> 1273 <varlistentry> 1274 <term><parameter>dest</parameter></term> 1275 <listitem><para></para></listitem> 1276 </varlistentry> 1277 <varlistentry> 1278 <term><parameter>prog</parameter></term> 1279 <listitem><para></para></listitem> 1280 </varlistentry> 1281 </variablelist> 1282 </sect3> 1283 1284 <sect3 id=remoteload xreflabel="remote_load procedure"> 1285 <title>Remote_load Procedure</title> 1286 1287 <para></para> 1288 1289 <funcsynopsis role="tcl"> 1290 <funcdef><function>remote_load</function></funcdef> 1291 <paramdef><parameter>dest</parameter> 1292 <parameter>prog</parameter> 1293 <parameter>args</parameter></paramdef> 1294 </funcsynopsis> 1295 <variablelist> 1296 <varlistentry> 1297 <term><parameter>dest</parameter></term> 1298 <listitem><para></para></listitem> 1299 </varlistentry> 1300 <varlistentry> 1301 <term><parameter>prog</parameter></term> 1302 <listitem><para></para></listitem> 1303 </varlistentry> 1304 <varlistentry> 1305 <term><parameter>args</parameter></term> 1306 <listitem><para></para></listitem> 1307 </varlistentry> 1308 </variablelist> 1309 </sect3> 1310 1311 <sect3 id=remoteopen xreflabel="remote_open procedure"> 1312 <title>Remote_open Procedure</title> 1313 1314 <para></para> 1315 1316 <funcsynopsis role="tcl"> 1317 <funcdef><function>remote_open</function></funcdef> 1318 <paramdef><parameter>type</parameter></paramdef> 1319 </funcsynopsis> 1320 <variablelist> 1321 <varlistentry> 1322 <term><parameter>type</parameter></term> 1323 <listitem><para>This is passed <option>host</option> or 1324 <option>target</option>. Host or target refers to 1325 whether it is a connection to a remote target, or a 1326 remote host. This opens the connection to the desired 1327 target or host using the default values in the 1328 configuration system. It returns that 1329 <symbol>spawn_id</symbol> of the process that manages 1330 the connection. This value can be used in 1331 <productname>Expect</productname> or 1332 <command>exp_send</command> statements, or passed to 1333 other procedures that need the connection process's 1334 id. This also sets the <symbol>fileid</symbol> field in 1335 the <symbol>target_info</symbol> array.</para></listitem> 1336 </varlistentry> 1337 </variablelist> 1338 </sect3> 1339 1340 <sect3 id=remotepopconn xreflabel="remote_pop_conn procedure"> 1341 <title>Remote_pop_conn Procedure</title> 1342 1343 <para></para> 1344 1345 <funcsynopsis role="tcl"> 1346 <funcdef><function>remote_pop_conn</function></funcdef> 1347 <paramdef><parameter>host</parameter></paramdef> 1348 </funcsynopsis> 1349 <variablelist> 1350 <varlistentry> 1351 <term><parameter>host</parameter></term> 1352 <listitem><para></para></listitem> 1353 </varlistentry> 1354 </variablelist> 1355 </sect3> 1356 1357 <sect3 id=remotepushconn xreflabel="remote_push_conn procedure"> 1358 <title>Remote_push_conn Procedure</title> 1359 1360 <para></para> 1361 1362 <funcsynopsis role="tcl"> 1363 <funcdef><function>remote_push_conn</function></funcdef> 1364 <paramdef><parameter>host</parameter></paramdef> 1365 </funcsynopsis> 1366 <variablelist> 1367 <varlistentry> 1368 <term><parameter>host</parameter></term> 1369 <listitem><para></para></listitem> 1370 </varlistentry> 1371 </variablelist> 1372 </sect3> 1373 1374 <sect3 id=remoterawbinary xreflabel="remote_raw_binary procedure"> 1375 <title>Remote_raw_binary Procedure</title> 1376 1377 <para></para> 1378 1379 <funcsynopsis role="tcl"> 1380 <funcdef><function>remote_raw_binary</function></funcdef> 1381 <paramdef><parameter>host</parameter></paramdef> 1382 </funcsynopsis> 1383 <variablelist> 1384 <varlistentry> 1385 <term><parameter>host</parameter></term> 1386 <listitem><para></para></listitem> 1387 </varlistentry> 1388 </variablelist> 1389 </sect3> 1390 1391 <sect3 id=remoterawclose xreflabel="remote_raw_close procedure"> 1392 <title>Remote_raw_close Procedure</title> 1393 1394 <para></para> 1395 1396 <funcsynopsis role="tcl"> 1397 <funcdef><function>remote_raw_close</function></funcdef> 1398 <paramdef><parameter>host</parameter></paramdef> 1399 </funcsynopsis> 1400 <variablelist> 1401 <varlistentry> 1402 <term><parameter>host</parameter></term> 1403 <listitem><para></para></listitem> 1404 </varlistentry> 1405 </variablelist> 1406 </sect3> 1407 1408 <sect3 id=remoterawfile xreflabel="remote_raw_file procedure"> 1409 <title>Remote_raw_file Procedure</title> 1410 1411 <para></para> 1412 1413 <funcsynopsis role="tcl"> 1414 <funcdef><function>remote_raw_file</function></funcdef> 1415 <paramdef><parameter>dest</parameter> 1416 <parameter>args</parameter></paramdef> 1417 </funcsynopsis> 1418 <variablelist> 1419 <varlistentry> 1420 <term><parameter>dest</parameter></term> 1421 <listitem><para></para></listitem> 1422 </varlistentry> 1423 <varlistentry> 1424 <term><parameter>args</parameter></term> 1425 <listitem><para></para></listitem> 1426 </varlistentry> 1427 </variablelist> 1428 </sect3> 1429 1430 <sect3 id=remoterawld xreflabel="remote_raw_ld procedure"> 1431 <title>remote_raw_ld Procedure</title> 1432 1433 <para></para> 1434 1435 <funcsynopsis role="tcl"> 1436 <funcdef><function>remote_raw_ld</function></funcdef> 1437 <paramdef><parameter>dest</parameter> 1438 <parameter>prog</parameter></paramdef> 1439 </funcsynopsis> 1440 <variablelist> 1441 <varlistentry> 1442 <term><parameter>dest</parameter></term> 1443 <listitem><para></para></listitem> 1444 </varlistentry> 1445 <varlistentry> 1446 <term><parameter>prog</parameter></term> 1447 <listitem><para></para></listitem> 1448 </varlistentry> 1449 </variablelist> 1450 </sect3> 1451 1452 <sect3 id=remoterawload xreflabel="remote_raw_load procedure"> 1453 <title>Remote_raw_load Procedure</title> 1454 1455 <para></para> 1456 1457 <funcsynopsis role="tcl"> 1458 <funcdef><function>remote_raw_load</function></funcdef> 1459 <paramdef><parameter>dest</parameter> 1460 <parameter>prog</parameter> 1461 <parameter>args</parameter></paramdef> 1462 </funcsynopsis> 1463 <variablelist> 1464 <varlistentry> 1465 <term><parameter>dest</parameter></term> 1466 <listitem><para></para></listitem> 1467 </varlistentry> 1468 <varlistentry> 1469 <term><parameter>prog</parameter></term> 1470 <listitem><para></para></listitem> 1471 </varlistentry> 1472 <varlistentry> 1473 <term><parameter>args</parameter></term> 1474 <listitem><para></para></listitem> 1475 </varlistentry> 1476 </variablelist> 1477 </sect3> 1478 1479 <sect3 id=remoterawopen xreflabel="remote_raw_open procedure"> 1480 <title>Remote_raw_open Procedure</title> 1481 1482 <para></para> 1483 1484 <funcsynopsis role="tcl"> 1485 <funcdef><function>remote_raw_open</function></funcdef> 1486 <paramdef><parameter>args</parameter></paramdef> 1487 </funcsynopsis> 1488 <variablelist> 1489 <varlistentry> 1490 <term><parameter>args</parameter></term> 1491 <listitem><para></para></listitem> 1492 </varlistentry> 1493 </variablelist> 1494 </sect3> 1495 1496 <sect3 id=remoterawsend xreflabel="remote_raw_send procedure"> 1497 <title>Remote_raw_send Procedure</title> 1498 1499 <para></para> 1500 1501 <funcsynopsis role="tcl"> 1502 <funcdef><function>remote_raw_send</function></funcdef> 1503 <paramdef><parameter>dest</parameter> 1504 <parameter>string</parameter></paramdef> 1505 </funcsynopsis> 1506 <variablelist> 1507 <varlistentry> 1508 <term><parameter>dest</parameter></term> 1509 <listitem><para></para></listitem> 1510 </varlistentry> 1511 <varlistentry> 1512 <term><parameter>string</parameter></term> 1513 <listitem><para></para></listitem> 1514 </varlistentry> 1515 </variablelist> 1516 </sect3> 1517 1518 <sect3 id=remoterawspawn xreflabel="remote_raw_spawn procedure"> 1519 <title>Remote_raw_spawn Procedure</title> 1520 1521 <para></para> 1522 1523 <funcsynopsis role="tcl"> 1524 <funcdef><function>remote_raw_spawn</function></funcdef> 1525 <paramdef><parameter>dest</parameter> 1526 <parameter>commandline</parameter></paramdef> 1527 </funcsynopsis> 1528 <variablelist> 1529 <varlistentry> 1530 <term><parameter>dest</parameter></term> 1531 <listitem><para></para></listitem> 1532 </varlistentry> 1533 <varlistentry> 1534 <term><parameter>commandline</parameter></term> 1535 <listitem><para></para></listitem> 1536 </varlistentry> 1537 </variablelist> 1538 </sect3> 1539 1540 <sect3 id=remoterawtransmit xreflabel="remote_raw_transmit 1541 procedure"> 1542 <title>Remote_raw_transmit Procedure</title> 1543 1544 <para></para> 1545 1546 <funcsynopsis role="tcl"> 1547 <funcdef><function>remote_raw_transmit</function></funcdef> 1548 <paramdef><parameter>dest</parameter> 1549 <parameter>file</parameter></paramdef> 1550 </funcsynopsis> 1551 <variablelist> 1552 <varlistentry> 1553 <term><parameter>dest</parameter></term> 1554 <listitem><para></para></listitem> 1555 </varlistentry> 1556 <varlistentry> 1557 <term><parameter>file</parameter></term> 1558 <listitem><para></para></listitem> 1559 </varlistentry> 1560 </variablelist> 1561 </sect3> 1562 1563 <sect3 id=remoterawwait xreflabel="remote_raw_wait procedure"> 1564 <title>Remote_raw_wait Procedure</title> 1565 1566 <para></para> 1567 1568 <funcsynopsis role="tcl"> 1569 <funcdef><function>remote_raw_wait</function></funcdef> 1570 <paramdef><parameter>dest</parameter> 1571 <parameter>timeout</parameter></paramdef> 1572 </funcsynopsis> 1573 <variablelist> 1574 <varlistentry> 1575 <term><parameter>dest</parameter></term> 1576 <listitem><para></para></listitem> 1577 </varlistentry> 1578 <varlistentry> 1579 <term><parameter>timeout</parameter></term> 1580 <listitem><para></para></listitem> 1581 </varlistentry> 1582 </variablelist> 1583 </sect3> 1584 1585 <sect3 id=remotereboot xreflabel="remote_reboot procedure"> 1586 <title>Remote_reboot Procedure</title> 1587 1588 <para></para> 1589 1590 <funcsynopsis role="tcl"> 1591 <funcdef><function>remote_reboot</function></funcdef> 1592 <paramdef><parameter>host</parameter></paramdef> 1593 </funcsynopsis> 1594 <variablelist> 1595 <varlistentry> 1596 <term><parameter>host</parameter></term> 1597 <listitem><para></para></listitem> 1598 </varlistentry> 1599 </variablelist> 1600 </sect3> 1601 1602 <sect3 id=remotesend xreflabel="remote_send procedure"> 1603 <title>Remote_send Procedure</title> 1604 1605 <para></para> 1606 1607 <funcsynopsis role="tcl"> 1608 <funcdef><function>remote_send</function></funcdef> 1609 <paramdef><parameter>dest</parameter> 1610 <parameter>string</parameter></paramdef> 1611 </funcsynopsis> 1612 <variablelist> 1613 <varlistentry> 1614 <term><parameter>dest</parameter></term> 1615 <listitem><para></para></listitem> 1616 </varlistentry> 1617 <varlistentry> 1618 <term><parameter>string</parameter></term> 1619 <listitem><para></para></listitem> 1620 </varlistentry> 1621 </variablelist> 1622 </sect3> 1623 1624 <sect3 id=remotespawn xreflabel="remote_spawn procedure"> 1625 <title>Remote_spawn Procedure</title> 1626 1627 <para></para> 1628 1629 <funcsynopsis role="tcl"> 1630 <funcdef><function>remote_spawn</function></funcdef> 1631 <paramdef><parameter>dest</parameter> 1632 <parameter>commandline</parameter> 1633 <parameter>args</parameter></paramdef> 1634 </funcsynopsis> 1635 <variablelist> 1636 <varlistentry> 1637 <term><parameter>dest</parameter></term> 1638 <listitem><para></para></listitem> 1639 </varlistentry> 1640 <varlistentry> 1641 <term><parameter>commandline</parameter></term> 1642 <listitem><para></para></listitem> 1643 </varlistentry> 1644 <varlistentry> 1645 <term><parameter>args</parameter></term> 1646 <listitem><para></para></listitem> 1647 </varlistentry> 1648 </variablelist> 1649 </sect3> 1650 1651 <sect3 id=remoteswapconn xreflabel="remote_swap_conn procedure"> 1652 <title>Remote_swap_conn Procedure</title> 1653 1654 <para></para> 1655 1656 <funcsynopsis role="tcl"> 1657 <funcdef><function>remote_swap_conn</function></funcdef> 1658 <paramdef><parameter>host</parameter></paramdef> 1659 </funcsynopsis> 1660 <variablelist> 1661 <varlistentry> 1662 <term><parameter></parameter></term> 1663 <listitem><para></para></listitem> 1664 </varlistentry> 1665 </variablelist> 1666 </sect3> 1667 1668 <sect3 id=remotetransmit xreflabel="remote_transmit procedure"> 1669 <title>Remote_transmit Procedure</title> 1670 1671 <para></para> 1672 1673 <funcsynopsis role="tcl"> 1674 <funcdef><function>remote_transmit</function></funcdef> 1675 <paramdef><parameter>dest</parameter> 1676 <parameter>file</parameter></paramdef> 1677 </funcsynopsis> 1678 <variablelist> 1679 <varlistentry> 1680 <term><parameter>dest</parameter></term> 1681 <listitem><para></para></listitem> 1682 </varlistentry> 1683 <varlistentry> 1684 <term><parameter>file</parameter></term> 1685 <listitem><para></para></listitem> 1686 </varlistentry> 1687 </variablelist> 1688 </sect3> 1689 1690 <sect3 id=remoteupload xreflabel="remote_upload procedure"> 1691 <title>Remote_upload Procedure</title> 1692 1693 <para></para> 1694 1695 <funcsynopsis role="tcl"> 1696 <funcdef><function>remote_upload</function></funcdef> 1697 <paramdef><parameter>dest</parameter> 1698 <parameter>srcfile</parameter> 1699 <parameter>arg</parameter></paramdef> 1700 </funcsynopsis> 1701 <variablelist> 1702 <varlistentry> 1703 <term><parameter>dest</parameter></term> 1704 <listitem><para></para></listitem> 1705 </varlistentry> 1706 <varlistentry> 1707 <term><parameter>srcfile</parameter></term> 1708 <listitem><para></para></listitem> 1709 </varlistentry> 1710 <varlistentry> 1711 <term><parameter>arg</parameter></term> 1712 <listitem><para></para></listitem> 1713 </varlistentry> 1714 </variablelist> 1715 </sect3> 1716 1717 <sect3 id=remotewait xreflabel="remote_wait procedure"> 1718 <title>Remote_wait Procedure</title> 1719 1720 <para></para> 1721 1722 <funcsynopsis role="tcl"> 1723 <funcdef><function>remote_wait</function></funcdef> 1724 <paramdef><parameter>dest</parameter> 1725 <parameter>timeout</parameter></paramdef> 1726 </funcsynopsis> 1727 <variablelist> 1728 <varlistentry> 1729 <term><parameter>dest</parameter></term> 1730 <listitem><para></para></listitem> 1731 </varlistentry> 1732 <varlistentry> 1733 <term><parameter>timeout</parameter></term> 1734 <listitem><para></para></listitem> 1735 </varlistentry> 1736 </variablelist> 1737 </sect3> 1738 1739 <sect3 id=standardclose xreflabel="standard_close procedure"> 1740 <title>Standard_close Procedure</title> 1741 1742 <para></para> 1743 1744 <funcsynopsis role="tcl"> 1745 <funcdef><function>standard_close</function></funcdef> 1746 <paramdef><parameter>host</parameter></paramdef> 1747 </funcsynopsis> 1748 <variablelist> 1749 <varlistentry> 1750 <term><parameter>host</parameter></term> 1751 <listitem><para></para></listitem> 1752 </varlistentry> 1753 </variablelist> 1754 </sect3> 1755 1756 <sect3 id=standarddownload xreflabel="standard_download procedure"> 1757 <title>Standard_download Procedure</title> 1758 1759 <para></para> 1760 1761 <funcsynopsis role="tcl"> 1762 <funcdef><function>standard_download</function></funcdef> 1763 <paramdef><parameter>dest</parameter> 1764 <parameter>file</parameter> 1765 <parameter>destfile</parameter></paramdef> 1766 </funcsynopsis> 1767 <variablelist> 1768 <varlistentry> 1769 <term><parameter>dest</parameter></term> 1770 <listitem><para></para></listitem> 1771 </varlistentry> 1772 <varlistentry> 1773 <term><parameter>file</parameter></term> 1774 <listitem><para></para></listitem> 1775 </varlistentry> 1776 <varlistentry> 1777 <term><parameter>destfile</parameter></term> 1778 <listitem><para></para></listitem> 1779 </varlistentry> 1780 </variablelist> 1781 </sect3> 1782 1783 <sect3 id=standardexec xreflabel="standard_exec procedure"> 1784 <title>Standard_exec Procedure</title> 1785 1786 <para></para> 1787 1788 <funcsynopsis role="tcl"> 1789 <funcdef><function>standard_exec</function></funcdef> 1790 <paramdef><parameter>hostname</parameter> 1791 <parameter>args</parameter></paramdef> 1792 </funcsynopsis> 1793 <variablelist> 1794 <varlistentry> 1795 <term><parameter>hostname</parameter></term> 1796 <listitem><para></para></listitem> 1797 </varlistentry> 1798 <varlistentry> 1799 <term><parameter>args</parameter></term> 1800 <listitem><para></para></listitem> 1801 </varlistentry> 1802 </variablelist> 1803 </sect3> 1804 1805 <sect3 id=standardfile xreflabel="standard_file procedure"> 1806 <title>Standard_file Procedure</title> 1807 1808 <para></para> 1809 1810 <funcsynopsis role="tcl"> 1811 <funcdef><function>standard_file</function></funcdef> 1812 <paramdef><parameter>dest</parameter 1813 <parameter>op</parameter 1814 <parameter>args</parameter></paramdef> 1815 </funcsynopsis> 1816 <variablelist> 1817 <varlistentry> 1818 <term><parameter></parameter></term> 1819 <listitem><para></para></listitem> 1820 </varlistentry> 1821 </variablelist> 1822 </sect3> 1823 1824 <sect3 id=standardload xreflabel="standard_load procedure"> 1825 <title>Standard_load Procedure</title> 1826 1827 <para></para> 1828 1829 <funcsynopsis role="tcl"> 1830 <funcdef><function>standard_load</function></funcdef> 1831 <paramdef><parameter>dest</parameter> 1832 <parameter>prog</parameter> 1833 <parameter>args</parameter></paramdef> 1834 </funcsynopsis> 1835 <variablelist> 1836 <varlistentry> 1837 <term><parameter>dest</parameter></term> 1838 <listitem><para></para></listitem> 1839 </varlistentry> 1840 <varlistentry> 1841 <term><parameter>prog</parameter></term> 1842 <listitem><para></para></listitem> 1843 </varlistentry> 1844 <varlistentry> 1845 <term><parameter>args</parameter></term> 1846 <listitem><para></para></listitem> 1847 </varlistentry> 1848 </variablelist> 1849 </sect3> 1850 1851 <sect3 id=standardreboot xreflabel="standard_reboot procedure"> 1852 <title>Standard_reboot Procedure</title> 1853 1854 <para></para> 1855 1856 <funcsynopsis role="tcl"> 1857 <funcdef><function>standard_reboot</function></funcdef> 1858 <paramdef><parameter>host</parameter></paramdef> 1859 </funcsynopsis> 1860 <variablelist> 1861 <varlistentry> 1862 <term><parameter>host</parameter></term> 1863 <listitem><para></para></listitem> 1864 </varlistentry> 1865 </variablelist> 1866 </sect3> 1867 1868 <sect3 id=standardsend xreflabel="standard_send procedure"> 1869 <title>Standard_send Procedure</title> 1870 1871 <para></para> 1872 1873 <funcsynopsis role="tcl"> 1874 <funcdef><function>standard_send</function></funcdef> 1875 <paramdef><parameter>dest</parameter> 1876 <parameter>string</parameter></paramdef> 1877 </funcsynopsis> 1878 <variablelist> 1879 <varlistentry> 1880 <term><parameter>dest</parameter></term> 1881 <listitem><para></para></listitem> 1882 </varlistentry> 1883 <varlistentry> 1884 <term><parameter>string</parameter></term> 1885 <listitem><para></para></listitem> 1886 </varlistentry> 1887 </variablelist> 1888 </sect3> 1889 1890 <sect3 id=standardspawn xreflabel="standard_spawn procedure"> 1891 <title>Standard_spawn Procedure</title> 1892 1893 <para></para> 1894 1895 <funcsynopsis role="tcl"> 1896 <funcdef><function>standard_spawn</function></funcdef> 1897 <paramdef><parameter>dest</parameter> 1898 <parameter>commandline</parameter></paramdef> 1899 </funcsynopsis> 1900 <variablelist> 1901 <varlistentry> 1902 <term><parameter>dest</parameter></term> 1903 <listitem><para></para></listitem> 1904 </varlistentry> 1905 <varlistentry> 1906 <term><parameter>commndline</parameter></term> 1907 <listitem><para></para></listitem> 1908 </varlistentry> 1909 </variablelist> 1910 </sect3> 1911 1912 <sect3 id=standardtransmit xreflabel="standard_transmit procedure"> 1913 <title>Standard_transmit Procedure</title> 1914 1915 <para></para> 1916 1917 <funcsynopsis role="tcl"> 1918 <funcdef><function>standard_transmit</function></funcdef> 1919 <paramdef><parameter>dest</parameter> 1920 <parameter>file</parameter></paramdef> 1921 </funcsynopsis> 1922 <variablelist> 1923 <varlistentry> 1924 <term><parameter>dest</parameter></term> 1925 <listitem><para></para></listitem> 1926 </varlistentry> 1927 <varlistentry> 1928 <term><parameter>file</parameter></term> 1929 <listitem><para></para></listitem> 1930 </varlistentry> 1931 </variablelist> 1932 </sect3> 1933 1934 <sect3 id=standardupload xreflabel="standard_upload procedure"> 1935 <title>Standard_upload Procedure</title> 1936 1937 <para></para> 1938 1939 <funcsynopsis role="tcl"> 1940 <funcdef><function>standard_upload</function></funcdef> 1941 <paramdef><parameter>dest srcfile destfile</parameter></paramdef> 1942 </funcsynopsis> 1943 <variablelist> 1944 <varlistentry> 1945 <term><parameter>dest</parameter></term> 1946 <listitem><para></para></listitem> 1947 </varlistentry> 1948 <varlistentry> 1949 <term><parameter>srcfile</parameter></term> 1950 <listitem><para></para></listitem> 1951 </varlistentry> 1952 <varlistentry> 1953 <term><parameter>destfile</parameter></term> 1954 <listitem><para></para></listitem> 1955 </varlistentry> 1956 </variablelist> 1957 </sect3> 1958 1959 <sect3 id=standardwait xreflabel="standard_wait procedure"> 1960 <title>Standard_wait Procedure</title> 1961 1962 <para></para> 1963 1964 <funcsynopsis role="tcl"> 1965 <funcdef><function>standard_wait</function></funcdef> 1966 <paramdef><parameter>dest</parameter> 1967 <parameter>timeout</parameter></paramdef> 1968 </funcsynopsis> 1969 <variablelist> 1970 <varlistentry> 1971 <term><parameter>dest</parameter></term> 1972 <listitem><para></para></listitem> 1973 </varlistentry> 1974 <varlistentry> 1975 <term><parameter>timeout</parameter></term> 1976 <listitem><para></para></listitem> 1977 </varlistentry> 1978 </variablelist> 1979 </sect3> 1980 1981 <sect3 id=unixcleanfilename xreflabel="unix_clean_filename 1982 procedure"> 1983 <title>Unix_clean_filename Procedure</title> 1984 1985 <para></para> 1986 1987 <funcsynopsis role="tcl"> 1988 <funcdef><function>unix_clean_filename</function></funcdef> 1989 <paramdef><parameter>dest</parameter> 1990 <parameter>file</parameter></paramdef> 1991 </funcsynopsis> 1992 <variablelist> 1993 <varlistentry> 1994 <term><parameter>dest</parameter></term> 1995 <listitem><para></para></listitem> 1996 </varlistentry> 1997 <varlistentry> 1998 <term><parameter>file</parameter></term> 1999 <listitem><para></para></listitem> 2000 </varlistentry> 2001 </variablelist> 2002 </sect3> 2003 2004<!-- FIXME: this doesn't seem to exist anymore 2005 <sect3 id=exitremoteshell xreflabel="exit_remote_shell procedure"> 2006 <title>exit_remote_shell Procedure</title> 2007 2008 <para></para> 2009 2010 <funcsynopsis role="tcl"> 2011 <funcdef><function>exit_remote_shell</function></funcdef> 2012 <paramdef><parameter>spawnid</parameter></paramdef> 2013 </funcsynopsis> 2014 <variablelist> 2015 <varlistentry> 2016 <term><parameter>spawnid</parameter></term> 2017 <listitem><para>Exits a remote process started by any 2018 of the connection procedures. <symbol>spawnid</symbol> 2019 is the result of the connection procedure that started 2020 the remote process.</para></listitem> 2021 </varlistentry> 2022 </variablelist> 2023 </sect3> 2024--> 2025 2026 </sect2> 2027 2028 <sect2 id=connprocs xreflabel="connprocs"> 2029 <title>Procedures For Using Utilities to Connect</title> 2030 2031 <para>telnet, rsh, tip, kermit</para> 2032 2033 <sect3 id=telnet xreflabel="telnet procedure"> 2034 <title>telnet Procedure</title> 2035 2036 <para></para> 2037 2038 <funcsynopsis role="tcl"> 2039 <funcdef><function>telnet</function></funcdef> 2040 <paramdef><parameter>hostname</parameter> 2041 <parameter>port</parameter></paramdef> 2042 </funcsynopsis> 2043 <funcsynopsis role="tcl"> 2044 <funcdef><function>rlogin</function></funcdef> 2045 <paramdef><parameter>hostname</parameter></paramdef> 2046 </funcsynopsis> 2047 </sect3> 2048 2049 <sect3 id=rsh xreflabel="rsh procedure"> 2050 <title>rsh Procedure</title> 2051 2052 <para></para> 2053 2054 <funcsynopsis role="tcl"> 2055 <funcdef><function>rsh</function></funcdef> 2056 <paramdef><parameter>hostname</parameter></paramdef> 2057 </funcsynopsis> 2058 <variablelist> 2059 <varlistentry> 2060 <term><parameter>hostname</parameter></term> 2061 <listitem><para>This refers to the IP address or name 2062 (for example, an entry in 2063 <filename>/etc/hosts</filename>) for this target. The 2064 procedure names reflect the Unix utility used to 2065 establish a connection. The optional 2066 <parameter>port</parameter> is used to specify the IP 2067 port number. The value of the 2068 <parameter>netport</parameter> field in the 2069 <symbol>target_info</symbol> array is used. (was 2070 <symbol>$netport</symbol>) This value has two parts, 2071 the hostname and the port number, seperated by a 2072 <emphasis>:</emphasis>. If host or target is used in 2073 the <symbol>hostname</symbol> field, than the 2074 config array is used for all information.</para></listitem> 2075 </varlistentry> 2076 </variablelist> 2077 </sect3> 2078 2079 <sect3 id=tip xreflabel="tip procedure"> 2080 <title>Tip Procedure</title> 2081 2082 <para></para> 2083 2084 <funcsynopsis role="tcl"> 2085 <funcdef><function>tip</function></funcdef> 2086 <paramdef><parameter>port</parameter></paramdef> 2087 </funcsynopsis> 2088 <variablelist> 2089 <varlistentry> 2090 <term><parameter>port</parameter></term> 2091 <listitem><para>Connect using the Unix utility 2092 <command>tip</command>. <parameter>Port</parameter>must 2093 be a name from the <productname>tip</productname> 2094 configuration file 2095 <filename>/etc/remote</filename>. Often, this is called 2096 <symbol>hardwire</symbol>, or something like 2097 <symbol>ttya</symbol>. This file holds all the 2098 configuration data for the serial port. The value of 2099 the <symbol>serial</symbol> field in the 2100 <symbol>target_info</symbol> array is used. (was 2101 <symbol>$serialport</symbol>) If <option>host</option> 2102 or <option>target</option> is used in the 2103 <parameter>port</parameter> field, than the config 2104 array is used for all information. the 2105 config array is used for all information.</para></listitem> 2106 </varlistentry> 2107 </variablelist> 2108 </sect3> 2109 2110 <sect3 id=kermit xreflabel="kermit procedure"> 2111 <title>Kermit Procedure</title> 2112 2113 <para></para> 2114 2115 <funcsynopsis role="tcl"> 2116 <funcdef><function>kermit</function></funcdef> 2117 <paramdef><parameter>port</parameter> 2118 <parameter>bps</parameter></paramdef> 2119 </funcsynopsis> 2120 <variablelist> 2121 <varlistentry> 2122 <term><parameter>port</parameter></term> 2123 <listitem><para>Connect using the program 2124 <command>kermit</command>. <parameter>Port</parameter> 2125 is the device name, 2126 e.g. <filename>/dev/ttyb</filename>. 2127 </para></listitem> 2128 </varlistentry> 2129 <varlistentry> 2130 <term><parameter>bps</parameter></term> 2131 <listitem><para><parameter>bps</parameter> is the line 2132 speed to use (in its per second) for the 2133 connection. The value of the <symbol>serial</symbol> 2134 field in the <symbol>target_info</symbol> array is 2135 used. (was <symbol>$serialport</symbol>) If 2136 <option>host</option> or <option>target</option> is 2137 used in the <parameter>port</parameter> field, than the 2138 config array is used for all information. the 2139 config array is used for all information.</para></listitem> 2140 </varlistentry> 2141 </variablelist> 2142 </sect3> 2143 2144 <sect3 id=kermitopen xreflabel="kermit_open procedure"> 2145 <title>kermit_open Procedure</title> 2146 2147 <para></para> 2148 2149 <funcsynopsis role="tcl"> 2150 <funcdef><function>kermit_open</function></funcdef> 2151 <paramdef><parameter>dest</parameter> 2152 <parameter>args</parameter></paramdef> 2153 </funcsynopsis> 2154 <variablelist> 2155 <varlistentry> 2156 <term><parameter>dest</parameter></term> 2157 <listitem><para></para></listitem> 2158 </varlistentry> 2159 <varlistentry> 2160 <term><parameter>args</parameter></term> 2161 <listitem><para></para></listitem> 2162 </varlistentry> 2163 </variablelist> 2164 </sect3> 2165 2166 <sect3 id=kermitcommand xreflabel="kermit_command procedure"> 2167 <title>Kermit_command Procedure</title> 2168 2169 <para></para> 2170 2171 <funcsynopsis role="tcl"> 2172 <funcdef><function>kermit_command</function></funcdef> 2173 <paramdef><parameter>dest</parameter> 2174 <parameter>args</parameter></paramdef> 2175 </funcsynopsis> 2176 <variablelist> 2177 <varlistentry> 2178 <term><parameter>dest</parameter></term> 2179 <listitem><para></para></listitem> 2180 </varlistentry> 2181 <varlistentry> 2182 <term><parameter>args</parameter></term> 2183 <listitem><para></para></listitem> 2184 </varlistentry> 2185 </variablelist> 2186 </sect3> 2187 2188 <sect3 id=kermitsend xreflabel="kermit_send procedure"> 2189 <title>Kermit_send Procedure</title> 2190 2191 <para></para> 2192 2193 <funcsynopsis role="tcl"> 2194 <funcdef><function>kermit_send</function></funcdef> 2195 <paramdef><parameter>dest string args</parameter></paramdef> 2196 </funcsynopsis> 2197 <variablelist> 2198 <varlistentry> 2199 <term><parameter>dest</parameter></term> 2200 <listitem><para></para></listitem> 2201 </varlistentry> 2202 <varlistentry> 2203 <term><parameter>string</parameter></term> 2204 <listitem><para></para></listitem> 2205 </varlistentry> 2206 <varlistentry> 2207 <term><parameter>args</parameter></term> 2208 <listitem><para></para></listitem> 2209 </varlistentry> 2210 </variablelist> 2211 </sect3> 2212 2213 <sect3 id=kermittransmit xreflabel="kermit_transmit procedure"> 2214 <title>Kermit_transmit Procedure</title> 2215 2216 <para></para> 2217 2218 <funcsynopsis role="tcl"> 2219 <funcdef><function>kermit_transmit</function></funcdef> 2220 <paramdef><parameter>dest</parameter> 2221 <parameter>file</parameter> 2222 <parameter>args</parameter></paramdef> 2223 </funcsynopsis> 2224 <variablelist> 2225 <varlistentry> 2226 <term><parameter>dest</parameter></term> 2227 <listitem><para></para></listitem> 2228 </varlistentry> 2229 <varlistentry> 2230 <term><parameter>file</parameter></term> 2231 <listitem><para></para></listitem> 2232 </varlistentry> 2233 <varlistentry> 2234 <term><parameter>args</parameter></term> 2235 <listitem><para></para></listitem> 2236 </varlistentry> 2237 </variablelist> 2238 </sect3> 2239 2240 <sect3 id=telnetopen xreflabel="telnet_open procedure"> 2241 <title>Telnet_open Procedure</title> 2242 2243 <para></para> 2244 2245 <funcsynopsis role="tcl"> 2246 <funcdef><function>telnet_open</function></funcdef> 2247 <paramdef><parameter>hostname</parameter> 2248 <parameter>args</parameter></paramdef> 2249 </funcsynopsis> 2250 <variablelist> 2251 <varlistentry> 2252 <term><parameter>hostname</parameter></term> 2253 <listitem><para></para></listitem> 2254 </varlistentry> 2255 <varlistentry> 2256 <term><parameter>args</parameter></term> 2257 <listitem><para></para></listitem> 2258 </varlistentry> 2259 </variablelist> 2260 </sect3> 2261 2262 <sect3 id=telnetbinary xreflabel="telnet_binary procedure"> 2263 <title>Telnet_binary Procedure</title> 2264 2265 <para></para> 2266 2267 <funcsynopsis role="tcl"> 2268 <funcdef><function>telnet_binary</function></funcdef> 2269 <paramdef><parameter>hostname</parameter></paramdef> 2270 </funcsynopsis> 2271 <variablelist> 2272 <varlistentry> 2273 <term><parameter>hostname</parameter></term> 2274 <listitem><para></para></listitem> 2275 </varlistentry> 2276 </variablelist> 2277 </sect3> 2278 2279 <sect3 id=telnettransmit xreflabel="telnet_transmit procedure"> 2280 <title>Telnet_transmit Procedure</title> 2281 2282 <para></para> 2283 2284 <funcsynopsis role="tcl"> 2285 <funcdef><function>telnet_transmit</function></funcdef> 2286 <paramdef><parameter>dest</parameter> 2287 <parameter>file</parameter> 2288 <parameter>args</parameter></paramdef> 2289 </funcsynopsis> 2290 <variablelist> 2291 <varlistentry> 2292 <term><parameter>dest</parameter></term> 2293 <listitem><para></para></listitem> 2294 </varlistentry> 2295 <varlistentry> 2296 <term><parameter>file</parameter></term> 2297 <listitem><para></para></listitem> 2298 </varlistentry> 2299 <varlistentry> 2300 <term><parameter>args</parameter></term> 2301 <listitem><para></para></listitem> 2302 </varlistentry> 2303 </variablelist> 2304 </sect3> 2305 2306 <sect3 id=tipopen xreflabel="tip_open procedure"> 2307 <title>Tip_open Procedure</title> 2308 2309 <para></para> 2310 2311 <funcsynopsis role="tcl"> 2312 <funcdef><function>tip_open</function></funcdef> 2313 <paramdef><parameter>hostname</parameter></paramdef> 2314 </funcsynopsis> 2315 <variablelist> 2316 <varlistentry> 2317 <term><parameter>hostname</parameter></term> 2318 <listitem><para></para></listitem> 2319 </varlistentry> 2320 </variablelist> 2321 </sect3> 2322 2323 <sect3 id=rloginopen xreflabel="rlogin_open procedure"> 2324 <title>Rlogin_open Procedure</title> 2325 2326 <para></para> 2327 2328 <funcsynopsis role="tcl"> 2329 <funcdef><function>rlogin_open</function></funcdef> 2330 <paramdef><parameter>arg</parameter></paramdef> 2331 </funcsynopsis> 2332 <variablelist> 2333 <varlistentry> 2334 <term><parameter>arg</parameter></term> 2335 <listitem><para></para></listitem> 2336 </varlistentry> 2337 </variablelist> 2338 </sect3> 2339 2340 <sect3 id=rloginspawn xreflabel="rlogin_spawn procedure"> 2341 <title>Rlogin_spawn Procedure</title> 2342 2343 <para></para> 2344 2345 <funcsynopsis role="tcl"> 2346 <funcdef><function>rlogin_spawn</function></funcdef> 2347 <paramdef><parameter>dest</parameter> 2348 <parameter>cmdline</parameter></paramdef> 2349 </funcsynopsis> 2350 <variablelist> 2351 <varlistentry> 2352 <term><parameter>dest</parameter></term> 2353 <listitem><para></para></listitem> 2354 </varlistentry> 2355 <varlistentry> 2356 <term><parameter>cmdline</parameter></term> 2357 <listitem><para></para></listitem> 2358 </varlistentry> 2359 </variablelist> 2360 </sect3> 2361 2362 <sect3 id=rshopen xreflabel="rsh_open procedure"> 2363 <title>Rsh_open Procedure</title> 2364 2365 <para></para> 2366 2367 <funcsynopsis role="tcl"> 2368 <funcdef><function>rsh_open</function></funcdef> 2369 <paramdef><parameter>hostname</parameter></paramdef> 2370 </funcsynopsis> 2371 <variablelist> 2372 <varlistentry> 2373 <term><parameter>hostname</parameter></term> 2374 <listitem><para></para></listitem> 2375 </varlistentry> 2376 </variablelist> 2377 </sect3> 2378 2379 <sect3 id=rshdownload xreflabel="rsh_download procedure"> 2380 <title>Rsh_download Procedure</title> 2381 2382 <para></para> 2383 2384 <funcsynopsis role="tcl"> 2385 <funcdef><function>rsh_download</function></funcdef> 2386 <paramdef><parameter>desthost</parameter> 2387 <parameter>srcfile</parameter> 2388 <parameter>destfile</parameter></paramdef> 2389 </funcsynopsis> 2390 <variablelist> 2391 <varlistentry> 2392 <term><parameter>desthost</parameter></term> 2393 <listitem><para></para></listitem> 2394 </varlistentry> 2395 <varlistentry> 2396 <term><parameter>srcfile</parameter></term> 2397 <listitem><para></para></listitem> 2398 </varlistentry> 2399 <varlistentry> 2400 <term><parameter>destfile</parameter></term> 2401 <listitem><para></para></listitem> 2402 </varlistentry> 2403 </variablelist> 2404 </sect3> 2405 2406 <sect3 id=rshupload xreflabel="rsh_upload procedure"> 2407 <title>Rsh_upload Procedure</title> 2408 2409 <para></para> 2410 2411 <funcsynopsis role="tcl"> 2412 <funcdef><function>rsh_upload</function></funcdef> 2413 <paramdef><parameter>desthost</parameter> 2414 <parameter>srcfile</parameter> 2415 <parameter>destfile</parameter></paramdef> 2416 </funcsynopsis> 2417 <variablelist> 2418 <varlistentry> 2419 <term><parameter>desthost</parameter></term> 2420 <listitem><para></para></listitem> 2421 </varlistentry> 2422 <varlistentry> 2423 <term><parameter>srcfile</parameter></term> 2424 <listitem><para></para></listitem> 2425 </varlistentry> 2426 <varlistentry> 2427 <term><parameter>destfile</parameter></term> 2428 <listitem><para></para></listitem> 2429 </varlistentry> 2430 </variablelist> 2431 </sect3> 2432 2433 <sect3 id=rshexec xreflabel="rsh_exec procedure"> 2434 <title>Rsh_exec Procedure</title> 2435 2436 <para></para> 2437 2438 <funcsynopsis role="tcl"> 2439 <funcdef><function>rsh_exec</function></funcdef> 2440 <paramdef><parameter>boardname</parameter> 2441 <parameter>cmd</parameter> 2442 <parameter>args</parameter></paramdef> 2443 </funcsynopsis> 2444 <variablelist> 2445 <varlistentry> 2446 <term><parameter>boardname</parameter></term> 2447 <listitem><para></para></listitem> 2448 </varlistentry> 2449 <varlistentry> 2450 <term><parameter>cmd</parameter></term> 2451 <listitem><para></para></listitem> 2452 </varlistentry> 2453 <varlistentry> 2454 <term><parameter>args</parameter></term> 2455 <listitem><para></para></listitem> 2456 </varlistentry> 2457 </variablelist> 2458 </sect3> 2459 2460 <sect3 id=ftpopen xreflabel="ftp_open procedure"> 2461 <title>Ftp_open Procedure</title> 2462 2463 <para></para> 2464 2465 <funcsynopsis role="tcl"> 2466 <funcdef><function>ftp_open</function></funcdef> 2467 <paramdef><parameter>host</parameter></paramdef> 2468 </funcsynopsis> 2469 <variablelist> 2470 <varlistentry> 2471 <term><parameter>host</parameter></term> 2472 <listitem><para></para></listitem> 2473 </varlistentry> 2474 </variablelist> 2475 </sect3> 2476 2477 <sect3 id=ftpupload xreflabel="ftp_upload procedure"> 2478 <title>Ftp_upload Procedure</title> 2479 2480 <para></para> 2481 2482 <funcsynopsis role="tcl"> 2483 <funcdef><function>ftp_upload</function></funcdef> 2484 <paramdef><parameter>host</parameter> 2485 <parameter>remotefile</parameter> 2486 <parameter>localfile</parameter></paramdef> 2487 </funcsynopsis> 2488 <variablelist> 2489 <varlistentry> 2490 <term><parameter>host</parameter></term> 2491 <listitem><para></para></listitem> 2492 </varlistentry> 2493 <varlistentry> 2494 <term><parameter>remotefile</parameter></term> 2495 <listitem><para></para></listitem> 2496 </varlistentry> 2497 <varlistentry> 2498 <term><parameter>localfile</parameter></term> 2499 <listitem><para></para></listitem> 2500 </varlistentry> 2501 </variablelist> 2502 </sect3> 2503 2504 <sect3 id=ftpdownload xreflabel="ftp_download procedure"> 2505 <title>Ftp_download Procedure</title> 2506 2507 <para></para> 2508 2509 <funcsynopsis role="tcl"> 2510 <funcdef><function>ftp_download</function></funcdef> 2511 <paramdef><parameter>host</parameter> 2512 <parameter>localfile</parameter> 2513 <parameter>remotefile</parameter></paramdef> 2514 </funcsynopsis> 2515 <variablelist> 2516 <varlistentry> 2517 <term><parameter>host</parameter></term> 2518 <listitem><para></para></listitem> 2519 </varlistentry> 2520 <varlistentry> 2521 <term><parameter>localfile</parameter></term> 2522 <listitem><para></para></listitem> 2523 </varlistentry> 2524 <varlistentry> 2525 <term><parameter>remotefile</parameter></term> 2526 <listitem><para></para></listitem> 2527 </varlistentry> 2528 </variablelist> 2529 </sect3> 2530 2531 <sect3 id=ftpclose xreflabel="ftp_close procedure"> 2532 <title>Ftp_close Procedure</title> 2533 2534 <para></para> 2535 2536 <funcsynopsis role="tcl"> 2537 <funcdef><function>ftp_close</function></funcdef> 2538 <paramdef><parameter>host</parameter></paramdef> 2539 </funcsynopsis> 2540 <variablelist> 2541 <varlistentry> 2542 <term><parameter>host</parameter></term> 2543 <listitem><para></para></listitem> 2544 </varlistentry> 2545 </variablelist> 2546 </sect3> 2547 2548 <sect3 id=tipdownload xreflabel="tip_download procedure"> 2549 <title>Tip_download Procedure</title> 2550 2551 <para></para> 2552 2553 <funcsynopsis role="tcl"> 2554 <funcdef><function>tip_download</function></funcdef> 2555 <paramdef><parameter>spawnid</parameter> 2556 <parameter>file</parameter></paramdef> 2557 </funcsynopsis> 2558 <variablelist> 2559 <varlistentry> 2560 <term><parameter>spawnid</parameter></term> 2561 <listitem><para>Download <option>file</option> to the 2562 process <symbol>spawnid</symbol> (the value returned 2563 when the connection was established), using the 2564 <command>~put</command> command under 2565 <productname>tip</productname>. Most often used for 2566 single board computers that require downloading 2567 programs in ASCII S-records. Returns 2568 <emphasis>1</emphasis> if an error occurs, 2569 <emphasis>0</emphasis> otherwise.</para></listitem> 2570 </varlistentry> 2571 <varlistentry> 2572 <term><parameter>file</parameter></term> 2573 <listitem><para>This is the filename to 2574 downlaod.</para></listitem> 2575 </varlistentry> 2576 </variablelist> 2577 </sect3> 2578 </sect2> 2579 2580 <sect2 id=targetprocs> 2581 <title>Procedures For Target Boards</title> 2582 2583 <para></para> 2584 2585 <sect3 id=defaultlink xreflabel="default_link procedure"> 2586 <title>Default_link Procedure</title> 2587 2588 <para></para> 2589 2590 <funcsynopsis role="tcl"> 2591 <funcdef><function>default_link</function></funcdef> 2592 <paramdef><parameter>board</parameter> 2593 <parameter>objects</parameter> 2594 <parameter>destfile</parameter> 2595 <parameter>flags</parameter></paramdef> 2596 </funcsynopsis> 2597 <variablelist> 2598 <varlistentry> 2599 <term><parameter>board</parameter></term> 2600 <listitem><para></para></listitem> 2601 </varlistentry> 2602 <varlistentry> 2603 <term><parameter>objects</parameter></term> 2604 <listitem><para></para></listitem> 2605 </varlistentry> 2606 <varlistentry> 2607 <term><parameter>destfile</parameter></term> 2608 <listitem><para></para></listitem> 2609 </varlistentry> 2610 <varlistentry> 2611 <term><parameter>flags</parameter></term> 2612 <listitem><para></para></listitem> 2613 </varlistentry> 2614 </variablelist> 2615 </sect3> 2616 2617 <sect3 id=defaulttargetassemble xreflabel="default_target_assemble 2618 procedure"> 2619 <title>Default_target_assemble Procedure</title> 2620 2621 <para></para> 2622 2623 <funcsynopsis role="tcl"> 2624 <funcdef><function>default_target_assemble</function></funcdef> 2625 <paramdef><parameter>source</parameter> 2626 <parameter>destfile</parameter> 2627 <parameter>flags</parameter></paramdef> 2628 </funcsynopsis> 2629 <variablelist> 2630 <varlistentry> 2631 <term><parameter>source</parameter></term> 2632 <listitem><para></para></listitem> 2633 </varlistentry> 2634 <varlistentry> 2635 <term><parameter>destfile</parameter></term> 2636 <listitem><para></para></listitem> 2637 </varlistentry> 2638 <varlistentry> 2639 <term><parameter>flags</parameter></term> 2640 <listitem><para></para></listitem> 2641 </varlistentry> 2642 </variablelist> 2643 </sect3> 2644 2645 <sect3 id=defaulttargetcompile xreflabel="default_target_compile 2646 procedure"> 2647 <title>default_target_compile Procedure</title> 2648 2649 <para></para> 2650 2651 <funcsynopsis role="tcl"> 2652 <funcdef><function>default_target_compile</function></funcdef> 2653 <paramdef><parameter>source</parameter> 2654 <parameter>destfile</parameter> 2655 <parameter>type</parameter> 2656 <parameter>options</parameter></paramdef> 2657 </funcsynopsis> 2658 <variablelist> 2659 <varlistentry> 2660 <term><parameter>source</parameter></term> 2661 <listitem><para></para></listitem> 2662 </varlistentry> 2663 <varlistentry> 2664 <term><parameter>destfile</parameter></term> 2665 <listitem><para></para></listitem> 2666 </varlistentry> 2667 <varlistentry> 2668 <term><parameter>type</parameter></term> 2669 <listitem><para></para></listitem> 2670 </varlistentry> 2671 <varlistentry> 2672 <term><parameter>options</parameter></term> 2673 <listitem><para></para></listitem> 2674 </varlistentry> 2675 </variablelist> 2676 </sect3> 2677 2678 <sect3 id=popconfig xreflabel="pop_config procedure"> 2679 <title>Pop_config Procedure</title> 2680 2681 <para></para> 2682 2683 <funcsynopsis role="tcl"> 2684 <funcdef><function>pop_config</function></funcdef> 2685 <paramdef><parameter>type</parameter></paramdef> 2686 </funcsynopsis> 2687 <variablelist> 2688 <varlistentry> 2689 <term><parameter>type</parameter></term> 2690 <listitem><para></para></listitem> 2691 </varlistentry> 2692 </variablelist> 2693 </sect3> 2694 2695 <sect3 id=prunewarnings xreflabel="prune_warnings procedure"> 2696 <title>Prune_warnings Procedure</title> 2697 2698 <para></para> 2699 2700 <funcsynopsis role="tcl"> 2701 <funcdef><function>prune_warnings</function></funcdef> 2702 <paramdef><parameter>text</parameter></paramdef> 2703 </funcsynopsis> 2704 <variablelist> 2705 <varlistentry> 2706 <term><parameter>text</parameter></term> 2707 <listitem><para></para></listitem> 2708 </varlistentry> 2709 </variablelist> 2710 </sect3> 2711 2712 <sect3 id=pushbuild xreflabel="push_build procedure"> 2713 <title>Push_build Procedure</title> 2714 2715 <para></para> 2716 2717 <funcsynopsis role="tcl"> 2718 <funcdef><function>push_build</function></funcdef> 2719 <paramdef><parameter>name</parameter></paramdef> 2720 </funcsynopsis> 2721 <variablelist> 2722 <varlistentry> 2723 <term><parameter>name</parameter></term> 2724 <listitem><para></para></listitem> 2725 </varlistentry> 2726 </variablelist> 2727 </sect3> 2728 2729 <sect3 id=pushconfig xreflabel="push_config procedure"> 2730 <title>push_config Procedure</title> 2731 2732 <para></para> 2733 2734 <funcsynopsis role="tcl"> 2735 <funcdef><function>push_config</function></funcdef> 2736 <paramdef><parameter>type</parameter> 2737 <parameter>name</parameter></paramdef> 2738 </funcsynopsis> 2739 <variablelist> 2740 <varlistentry> 2741 <term><parameter>type</parameter></term> 2742 <listitem><para></para></listitem> 2743 </varlistentry> 2744 <varlistentry> 2745 <term><parameter>name</parameter></term> 2746 <listitem><para></para></listitem> 2747 </varlistentry> 2748 </variablelist> 2749 </sect3> 2750 2751 <sect3 id=reboottarget xreflabel="reboot_target procedure"> 2752 <title>Reboot_target Procedure</title> 2753 2754 <para></para> 2755 2756 <funcsynopsis role="tcl"> 2757 <funcdef><function>reboot_target</function></funcdef> 2758 <paramdef><parameter></parameter></paramdef> 2759 </funcsynopsis> 2760 </sect3> 2761 2762 <sect3 id=targetassemble xreflabel="target_assemble procedure"> 2763 <title>Target_assemble Procedure</title> 2764 2765 <para></para> 2766 2767 <funcsynopsis role="tcl"> 2768 <funcdef><function>target_assemble</function></funcdef> 2769 <paramdef><parameter>source destfile flags</parameter></paramdef> 2770 </funcsynopsis> 2771 <variablelist> 2772 <varlistentry> 2773 <term><parameter>source</parameter></term> 2774 <listitem><para></para></listitem> 2775 </varlistentry> 2776 <varlistentry> 2777 <term><parameter>destfile</parameter></term> 2778 <listitem><para></para></listitem> 2779 </varlistentry> 2780 <varlistentry> 2781 <term><parameter>flags</parameter></term> 2782 <listitem><para></para></listitem> 2783 </varlistentry> 2784 </variablelist> 2785 </sect3> 2786 2787 <sect3 id=targetcompile xreflabel="target_compile procedure"> 2788 <title>Target_compile Procedure</title> 2789 2790 <para></para> 2791 2792 <funcsynopsis role="tcl"> 2793 <funcdef><function>target_compile</function></funcdef> 2794 <paramdef><parameter>source</parameter> 2795 <parameter>destfile</parameter> 2796 <parameter>type</parameter> 2797 <parameter>options</parameter></paramdef> 2798 </funcsynopsis> 2799 <variablelist> 2800 <varlistentry> 2801 <term><parameter>source</parameter></term> 2802 <listitem><para></para></listitem> 2803 </varlistentry> 2804 <varlistentry> 2805 <term><parameter>destfile</parameter></term> 2806 <listitem><para></para></listitem> 2807 </varlistentry> 2808 <varlistentry> 2809 <term><parameter>type</parameter></term> 2810 <listitem><para></para></listitem> 2811 </varlistentry> 2812 <varlistentry> 2813 <term><parameter>options</parameter></term> 2814 <listitem><para></para></listitem> 2815 </varlistentry> 2816 </variablelist> 2817 </sect3> 2818 </sect2> 2819 2820 <sect2 id=targetdb xreflabel="target database library file "> 2821 <title>Target Database Procedures</title> 2822 2823 <sect3 id=boardinfo xreflabel="board_info procedure"> 2824 <title>Board_info Procedure</title> 2825 2826 <para></para> 2827 2828 <funcsynopsis role="tcl"> 2829 <funcdef><function>board_info</function></funcdef> 2830 <paramdef><parameter>machine</parameter> 2831 <parameter>op</parameter> 2832 <parameter>args</parameter></paramdef> 2833 </funcsynopsis> 2834 <variablelist> 2835 <varlistentry> 2836 <term><parameter>machine</parameter></term> 2837 <listitem><para></para></listitem> 2838 </varlistentry> 2839 <varlistentry> 2840 <term><parameter>op</parameter></term> 2841 <listitem><para></para></listitem> 2842 </varlistentry> 2843 <varlistentry> 2844 <term><parameter>args</parameter></term> 2845 <listitem><para></para></listitem> 2846 </varlistentry> 2847 </variablelist> 2848 </sect3> 2849 2850 <sect3 id=hostinfo xreflabel="host_info procedure"> 2851 <title>Host_info Procedure</title> 2852 2853 <para></para> 2854 2855 <funcsynopsis role="tcl"> 2856 <funcdef><function>host_info</function></funcdef> 2857 <paramdef><parameter>op</parameter> 2858 <parameter>args</parameter></paramdef> 2859 </funcsynopsis> 2860 <variablelist> 2861 <varlistentry> 2862 <term><parameter>op</parameter></term> 2863 <listitem><para></para></listitem> 2864 </varlistentry> 2865 <varlistentry> 2866 <term><parameter>args</parameter></term> 2867 <listitem><para></para></listitem> 2868 </varlistentry> 2869 </variablelist> 2870 </sect3> 2871 2872 <sect3 id=setboardinfo xreflabel="set_board_info procedure"> 2873 <title>Set_board_info Procedure</title> 2874 2875 <para></para> 2876 2877 <funcsynopsis role="tcl"> 2878 <funcdef><function>set_board_info</function></funcdef> 2879 <paramdef><parameter>entry</parameter> 2880 <parameter>value</parameter></paramdef> 2881 </funcsynopsis> 2882 <variablelist> 2883 <varlistentry> 2884 <term><parameter>entry</parameter></term> 2885 <listitem><para></para></listitem> 2886 </varlistentry> 2887 <varlistentry> 2888 <term><parameter>value</parameter></term> 2889 <listitem><para></para></listitem> 2890 </varlistentry> 2891 </variablelist> 2892 </sect3> 2893 2894 <sect3 id=setcurrtargetinfo xreflabel="set_currtarget_info 2895 procedure"> 2896 <title>Set_currtarget_info Procedure</title> 2897 2898 <para></para> 2899 2900 <funcsynopsis role="tcl"> 2901 <funcdef><function>set_currtarget_info</function></funcdef> 2902 <paramdef><parameter>entry</parameter> 2903 <parameter>value</parameter></paramdef> 2904 </funcsynopsis> 2905 <variablelist> 2906 <varlistentry> 2907 <term><parameter>entry</parameter></term> 2908 <listitem><para></para></listitem> 2909 </varlistentry> 2910 <varlistentry> 2911 <term><parameter>value</parameter></term> 2912 <listitem><para></para></listitem> 2913 </varlistentry> 2914 </variablelist> 2915 </sect3> 2916 2917 <sect3 id=targetinfo xreflabel="target_info procedure"> 2918 <title>Target_info Procedure</title> 2919 2920 <para></para> 2921 2922 <funcsynopsis role="tcl"> 2923 <funcdef><function>target_info</function></funcdef> 2924 <paramdef><parameter>op</parameter> 2925 <parameter>args</parameter></paramdef> 2926 </funcsynopsis> 2927 <variablelist> 2928 <varlistentry> 2929 <term><parameter>op</parameter></term> 2930 <listitem><para></para></listitem> 2931 </varlistentry> 2932 <varlistentry> 2933 <term><parameter>args</parameter></term> 2934 <listitem><para></para></listitem> 2935 </varlistentry> 2936 </variablelist> 2937 </sect3> 2938 2939 <sect3 id=unsetboardinfo xreflabel="unset_board_info procedure"> 2940 <title>Unset_board_info Procedure</title> 2941 2942 <para></para> 2943 2944 <funcsynopsis role="tcl"> 2945 <funcdef><function>unset_board_info</function></funcdef> 2946 <paramdef><parameter>entry</parameter></paramdef> 2947 </funcsynopsis> 2948 <variablelist> 2949 <varlistentry> 2950 <term><parameter>entry</parameter></term> 2951 <listitem><para></para></listitem> 2952 </varlistentry> 2953 </variablelist> 2954 </sect3> 2955 2956 <sect3 id=unsetcurrtargetinfo xreflabel="unset_currtarget_info 2957 procedure"> 2958 <title>Unset_currtarget_info Procedure</title> 2959 2960 <para></para> 2961 2962 <funcsynopsis role="tcl"> 2963 <funcdef><function>unset_currtarget_info</function></funcdef> 2964 <paramdef><parameter>entry</parameter></paramdef> 2965 </funcsynopsis> 2966 <variablelist> 2967 <varlistentry> 2968 <term><parameter>entry</parameter></term> 2969 <listitem><para></para></listitem> 2970 </varlistentry> 2971 </variablelist> 2972 </sect3> 2973 2974 <sect3 id=pushtarget xreflabel="push_target procedure"> 2975 <title>Push_target Procedure</title> 2976 2977 <para>This makes the target named <emphasis>name</emphasis> be the 2978 current target connection. The value of <emphasis>name</emphasis> is 2979 an index into the <symbol>target_info</symbol> array and is set in 2980 the global config file.</para> 2981 2982 <funcsynopsis role="tcl"> 2983 <funcdef><function>push_target</function></funcdef> 2984 <paramdef><parameter>name</parameter></paramdef> 2985 </funcsynopsis> 2986 <variablelist> 2987 <varlistentry> 2988 <term><parameter>name</parameter></term> 2989 <listitem><para>The name of the target to make current 2990 connection.</para></listitem> 2991 </varlistentry> 2992 </variablelist> 2993 </sect3> 2994 2995 <sect3 id=poptarget xreflabel="poptarget procedure"> 2996 <title>Pop_target Procedure</title> 2997 2998 <para>This unsets the current target connection.</para> 2999 3000 <funcsynopsis role="tcl"> 3001 <funcdef><function>pop_target</function></funcdef> 3002 <paramdef><parameter></parameter></paramdef> 3003 </funcsynopsis> 3004 </sect3> 3005 3006 <sect3 id=listtargets xreflabel="list_targets procedure"> 3007 <title>List_targets Procedure</title> 3008 3009 <para>This lists all the supported targets for this 3010 architecture.</para> 3011 3012 <funcsynopsis role="tcl"> 3013 <funcdef><function>list_targets</function></funcdef> 3014 <paramdef><parameter></parameter></paramdef> 3015 </funcsynopsis> 3016 </sect3> 3017 3018 <sect3 id=pushhost xreflabel="push_host procedure"> 3019 <title>Push_host Procedure</title> 3020 3021 <para>This makes the host named <emphasis>name</emphasis> be the 3022 current remote host connection. The value of 3023 <emphasis>name</emphasis> is an index into the 3024 <symbol>target_info</symbol> array and is set in the global config 3025 file.</para> 3026 3027 <funcsynopsis role="tcl"> 3028 <funcdef><function>push_host</function></funcdef> 3029 <paramdef><parameter>name</parameter></paramdef> 3030 </funcsynopsis> 3031 <variablelist> 3032 <varlistentry> 3033 <term><parameter>name</parameter></term> 3034 <listitem><para></para></listitem> 3035 </varlistentry> 3036 </variablelist> 3037 </sect3> 3038 3039 <sect3 id=pophost xreflabel="pop_host procedure"> 3040 <title>Pop_host Procedure</title> 3041 3042 <para>This unsets the current host connection.</para> 3043 3044 <funcsynopsis role="tcl"> 3045 <funcdef><function>pop_host</function></funcdef> 3046 <paramdef><parameter></parameter></paramdef> 3047 </funcsynopsis> 3048 </sect3> 3049 3050 <sect3 id=compile xreflabel="compile procedure"> 3051 <title>Compile Procedure</title> 3052 3053 <para>This invokes the compiler as set by CC to compile the 3054 file <filename>file</filename>. The default options for many cross 3055 compilation targets are <emphasis>guessed</emphasis> by DejaGnu, and 3056 these options can be added to by passing in more parameters as 3057 arguments to <command>compile</command>. Optionally, this will also 3058 use the value of the <emphasis>cflags</emphasis> field in the target 3059 config array. If the host is not the same as the build machines, then 3060 then compiler is run on the remote host using 3061 <command>execute_anywhere</command>.</para> 3062 3063 <funcsynopsis role="tcl"> 3064 <funcdef><function>compile</function></funcdef> 3065 <paramdef><parameter>file</parameter></paramdef> 3066 </funcsynopsis> 3067 <variablelist> 3068 <varlistentry> 3069 <term><parameter>file</parameter></term> 3070 <listitem><para></para></listitem> 3071 </varlistentry> 3072 </variablelist> 3073 </sect3> 3074 3075 <sect3 id=archive xreflabel="archive procedure"> 3076 <title>Archive Procedure</title> 3077 3078 <para>This produces an archive file. Any parameters passed to 3079 <command>archive</command> are used in addition to the default 3080 flags. Optionally, this will also use the value of the 3081 <emphasis>arflags</emphasis> field in the target config array. If the 3082 host is not the same as the build machines, then then archiver is run 3083 on the remote host using <command>execute_anywhere</command>.</para> 3084 3085 <funcsynopsis role="tcl"> 3086 <funcdef><function>archive</function></funcdef> 3087 <paramdef><parameter>file</parameter></paramdef> 3088 </funcsynopsis> 3089 <variablelist> 3090 <varlistentry> 3091 <term><parameter>file</parameter></term> 3092 <listitem><para></para></listitem> 3093 </varlistentry> 3094 </variablelist> 3095 </sect3> 3096 3097 <sect3 id=ranlib xreflabel="ranlib procedure"> 3098 <title>Ranlib Procedure</title> 3099 3100 <para>This generates an index for the archive file for systems that 3101 aren't POSIX yet. Any parameters passed to <command>ranlib</command> 3102 are used in for the flags.</para> 3103 3104 <funcsynopsis role="tcl"> 3105 <funcdef><function>ranlib</function></funcdef> 3106 <paramdef><parameter>file</parameter></paramdef> 3107 </funcsynopsis> 3108 <variablelist> 3109 <varlistentry> 3110 <term><parameter>file</parameter></term> 3111 <listitem><para></para></listitem> 3112 </varlistentry> 3113 </variablelist> 3114 </sect3> 3115 3116 <sect3 id=executeanywhere xreflabel="execute_anywhere procedure"> 3117 <title>Execute_anywhere Procedure</title> 3118 3119 <para>This executes the <emphasis>cmdline</emphasis> on the proper 3120 host. This should be used as a replacement for the Tcl command 3121 <command>exec</command> as this version utilizes the target config 3122 info to execute this command on the build machine or a remote 3123 host. All config information for the remote host must be setup to 3124 have this command work. If this is a canadian cross, (where we test a 3125 cross compiler that runs on a different host then where DejaGnu is 3126 running) then a connection is made to the remote host and the command 3127 is executed there. It returns either REMOTERROR (for an error) or the 3128 output produced when the command was executed. This is used for 3129 running the tool to be tested, not a test case.</para> 3130 3131 <funcsynopsis role="tcl"> 3132 <funcdef><function>execute_anywhere</function></funcdef> 3133 <paramdef><parameter>cmdline</parameter></paramdef> 3134 </funcsynopsis> 3135 <variablelist> 3136 <varlistentry> 3137 <term><parameter>cmdline</parameter></term> 3138 <listitem><para></para></listitem> 3139 </varlistentry> 3140 </variablelist> 3141 </sect3> 3142 3143 </sect2> 3144 <sect2 id=platformprocs xreflabel="platform dependant procedures"> 3145 <title>Platform Dependant Procedures</title> 3146 3147 <para>Each combination of target and tool requires some 3148 target-dependent procedures. The names of these procedures have 3149 a common form: the tool name, followed by an underbar 3150 <emphasis>_</emphasis>, and finally a suffix describing the 3151 procedure's purpose. For example, a procedure to extract the 3152 version from <productname>GDB</productname> is called 3153 <symbol>gdb_version</symbol>.</para> 3154 3155 <para><command>runtest</command> itself calls only two of these 3156 procedures, <symbol>${tool}_exit</symbol> and 3157 <symbol>${tool}_version</symbol>; these procedures use no 3158 arguments.</para> 3159 3160 <para>The other two procedures, <symbol>${tool}_start</symbol> 3161 and <symbol>${tool}_load</symbol>}, are only called by the test 3162 suites themselves (or by testsuite-specific initialization 3163 code); they may take arguments or not, depending on the 3164 conventions used within each testsuite.</para> 3165 3166 <para>The usual convention for return codes from any of these 3167 procedures (although it is not required by 3168 <command>runtest</command>) is to return <emphasis>0</emphasis> 3169 if the procedure succeeded, <emphasis>1</emphasis> if it failed, 3170 and <emphasis>-1</emphasis> if there was a communication error.</para> 3171 3172 <sect3 id=toolstart xreflabel="${tool}_start procedure"> 3173 <title>${tool}_start Procedure</title> 3174 3175 <para>Starts a particular tool. For an interactive tool, 3176 <function>${tool}_start</function> starts and initializes the 3177 tool, leaving the tool up and running for the test cases; an 3178 example is <function>gdb_start</function>, the start function 3179 for GDB. For a batch oriented tool, 3180 <function>${tool}_start</function> is optional; the recommended 3181 convention is to let <function>${tool}_start</function> run the 3182 tool, leaving the output in a variable called 3183 <function>comp_output</function>. Test scripts can then analyze 3184 <function>$comp_output</function> to determine the test results. 3185 An example of this second kind of start function is 3186 <function>gcc_start</function>, the start function for GCC.</para> 3187 3188 <para>DejaGnu itself does not call 3189 <function>${tool}_start</function>. The initialization 3190 module <function>${tool}_init.exp</function> must call 3191 <function>${tool}_start</function> for interactive tools; 3192 for batch-oriented tools, each individual test script calls 3193 <function>${tool}_start</function> (or makes other 3194 arrangements to run the tool).</para> 3195 3196 <funcsynopsis role="tcl"> 3197 <funcdef><function>${tool}_start</function></funcdef> 3198 <paramdef><parameter></parameter></paramdef> 3199 </funcsynopsis> 3200 </sect3> 3201 3202 <sect3 id=toolload xreflabel="${tool}_load procedure"> 3203 <title>${tool}_load Procedure</title> 3204 3205 <para>Loads something into a tool. For an interactive tool, 3206 this conditions the tool for a particular test case; for 3207 example, <function>gdb_load</function> loads a new 3208 executable file into the debugger. For batch oriented tools, 3209 <function>${tool}_load</function> may do nothing---though, 3210 for example, the GCC support uses 3211 <function>gcc_load</function> to load and run a binary on 3212 the target environment. Conventionally, 3213 <function>${tool}_load</function> leaves the output of any 3214 program it runs in a variable called 3215 <symbol>$exec_output</symbol>. Writing 3216 <function>${tool}_load</function> can be the most complex 3217 part of extending DejaGnu to a new tool or a new target, if 3218 it requires much communication coding or file 3219 downloading. Test scripts call 3220 <function>${tool}_load</function>.</para> 3221 3222 <funcsynopsis role="tcl"> 3223 <funcdef><function>${tool}_load</function></funcdef> 3224 <paramdef><parameter></parameter></paramdef> 3225 </funcsynopsis> 3226 </sect3> 3227 3228 <sect3 id=toolexit xreflabel="${tool}_exit procedure"> 3229 <title>${tool}_exit Procedure</title> 3230 3231 <para>Cleans up (if necessary) before DejaGnu exits. For 3232 interactive tools, this usually ends the interactive 3233 session. You can also use <function>${tool}_exit</function> 3234 to remove any temporary files left over from the 3235 tests. <command>runtest</command> calls 3236 <function>${tool}_exit</function>.</para> 3237 3238 <funcsynopsis role="tcl"> 3239 <funcdef><function>${tool}_exit</function></funcdef> 3240 <paramdef><parameter></parameter></paramdef> 3241 </funcsynopsis> 3242 </sect3> 3243 3244 <sect3 id=toolversion xreflabel="${tool}_version procedure"> 3245 <title>${tool}_version Procedure</title> 3246 3247 <para>Prints the version label and number for 3248 <symbol>${tool}</symbol>. This is called by the DejaGnu 3249 procedure that prints the final summary report. The output 3250 should consist of the full path name used for the tested 3251 tool, and its version number.</para> 3252 3253 <funcsynopsis role="tcl"> 3254 <funcdef><function>${tool}_version</function></funcdef> 3255 <paramdef><parameter></parameter></paramdef> 3256 </funcsynopsis> 3257 </sect3> 3258 3259 </sect2> 3260 3261 <sect2 id=utilprocs> 3262 <title>Utility Procedures</title> 3263 3264 <sect3 id=getdirs xreflabel="getdirs procedure"> 3265 <title>Getdirs Procedure</title> 3266 3267 <para>Returns a list of all the directories in the single 3268 directory a single directory that match an optional 3269 pattern. </para> 3270 3271 <funcsynopsis role="tcl"> 3272 <funcdef><function>getdirs</function></funcdef> 3273 <paramdef><parameter>rootdir</parameter> 3274 <parameter>pattern</parameter></paramdef> 3275 </funcsynopsis> 3276 <variablelist> 3277 <varlistentry> 3278 <term><parameter>args</parameter></term> 3279 <listitem><para></para></listitem> 3280 </varlistentry> 3281 <varlistentry> 3282 <term><parameter>pattern</parameter></term> 3283 <listitem><para>If you do not specify 3284 <parameter>pattern</parameter>, 3285 <function>Getdirs</function> assumes a default pattern of 3286 <emphasis>*</emphasis>. You may use the common shell 3287 wildcard characters in the pattern. If no directories 3288 match the pattern, then a NULL string is 3289 returned</para></listitem> 3290 </varlistentry> 3291 </variablelist> 3292 </sect3> 3293 3294 <sect3 id=find xreflabel="find procedure"> 3295 <title>Find Procedure</title> 3296 3297 <para>Search for files whose names match <emphasis>pattern</emphasis> 3298 (using shell wildcard characters for filename expansion). Search 3299 subdirectories recursively, starting at 3300 <emphasis>rootdir</emphasis>. The result is the list of files whose 3301 names match; if no files match, the result is empty. Filenames in the 3302 result include all intervening subdirectory names. If no files match 3303 the pattern, then a NULL string is returned.</para> 3304 3305 <funcsynopsis role="tcl"> 3306 <funcdef><function>find</function></funcdef> 3307 <paramdef><parameter>rootdir</parameter> 3308 <parameter>pattern</parameter></paramdef> 3309 </funcsynopsis> 3310 <variablelist> 3311 <varlistentry> 3312 <term><parameter>rootdir</parameter></term> 3313 <listitem><para>The top level directory to search the search 3314 from.</para></listitem> 3315 </varlistentry> 3316 <varlistentry> 3317 <term><parameter>pattern</parameter></term> 3318 <listitem><para>A csh "glob" style regular expression reprsenting 3319 the files to find.</para></listitem> 3320 </varlistentry> 3321 </variablelist> 3322 </sect3> 3323 3324 <sect3 id=which xreflabel="which procedure"> 3325 <title>Which Procedure</title> 3326 3327 <para>Searches the execution path for an executable file 3328 <emphasis>binary</emphasis>, like the the BSD <command>which</command> 3329 utility. This procedure uses the shell environment variable 3330 <emphasis>PATH</emphasis>. It returns <emphasis>0</emphasis> if the 3331 binary is not in the path, or if there is no <emphasis>PATH</emphasis> 3332 environment variable. If <command>binary</command> is in the path, it 3333 returns the full path to <command>binary</command>.</para> 3334 3335 <funcsynopsis role="tcl"> 3336 <funcdef><function>which</function></funcdef> 3337 <paramdef><parameter>file</parameter></paramdef> 3338 </funcsynopsis> 3339 <variablelist> 3340 <varlistentry> 3341 <term><parameter>binary</parameter></term> 3342 <listitem><para>The executable program or shell script to look 3343 for.</para></listitem> 3344 </varlistentry> 3345 </variablelist> 3346 </sect3> 3347 3348 <sect3 id=grep xreflabel="grep procedure"> 3349 <title>Grep Procedure</title> 3350 3351 <para>Search the file called <filename>filename</filename> (a fully 3352 specified path) for lines that contain a match for regular expression 3353 <emphasis>regexp</emphasis>. The result is a list of all the lines that 3354 match. If no lines match, the result is an empty string. Specify 3355 <emphasis>regexp</emphasis> using the standard regular expression style 3356 used by the Unix utility program grep.</para> 3357 3358 <para>Use the optional third argument <emphasis>line</emphasis> to 3359 start lines in the result with the line number in 3360 <filename>filename</filename>. (This argument is simply an option 3361 flag; type it just as shown <option>--line</option>.)</para> 3362 3363 <funcsynopsis role="tcl"> 3364 <funcdef><function>grep</function></funcdef> 3365 <paramdef><parameter>filename</parameter> 3366 <parameter>regexp</parameter> 3367 <parameter>--line</parameter></paramdef> 3368 </funcsynopsis> 3369 <variablelist> 3370 <varlistentry> 3371 <term><parameter>filename</parameter></term> 3372 <listitem><para>The file to search.</para></listitem> 3373 </varlistentry> 3374 <varlistentry> 3375 <term><parameter>regexp</parameter></term> 3376 <listitem><para>The Unix style regular expression (as used by the 3377 <command>grep</command> Unix utility) to search 3378 for.</para></listitem> 3379 </varlistentry> 3380 <varlistentry> 3381 <term><parameter>--line</parameter></term> 3382 <listitem><para>Prefix the line number to each line where the 3383 regexp matches.</para></listitem> 3384 </varlistentry> 3385 </variablelist> 3386 </sect3> 3387 3388 <sect3 id=prune xreflabel="prune procedure"> 3389 <title>Prune Procedure</title> 3390 3391 <para>Remove elements of the Tcl list <emphasis>list</emphasis>. 3392 Elements are fields delimited by spaces. The result is a copy of 3393 list, without any elements that match <emphasis>pattern</emphasis>. 3394 You can use the common shell wildcard characters to specify the 3395 pattern.</para> 3396 3397 <funcsynopsis role="tcl"> 3398 <funcdef><function>prune</function></funcdef> 3399 <paramdef><parameter>list</parameter> 3400 <parameter>pattern</parameter></paramdef> 3401 </funcsynopsis> 3402 <variablelist> 3403 <varlistentry> 3404 <term><parameter>list</parameter></term> 3405 <listitem><para>A Tcl list containing the original data. Commonly 3406 this is the output of a batch executed command, like running a 3407 compiler.</para></listitem> 3408 </varlistentry> 3409 <varlistentry> 3410 <term><parameter>pattern</parameter></term> 3411 <listitem><para>The csh shell "glob" style pattern to search 3412 for.</para></listitem> 3413 </varlistentry> 3414 </variablelist> 3415 3416 </sect3> 3417 3418 <sect3 id=slay xreflabel="slay procedure"> 3419 <title>Slay Procedure</title> 3420 3421 <para>This look in the process table for <emphasis>name</emphasis> 3422 and send it a unix SIGINT, killing the process. This will only work 3423 under Windows if you have Cygwin or another Unix subsystem for Windows 3424 installed.</para> 3425 3426 <funcsynopsis role="tcl"> 3427 <funcdef><function>slay</function></funcdef> 3428 <paramdef><parameter>name</parameter></paramdef> 3429 </funcsynopsis> 3430 <variablelist> 3431 <varlistentry> 3432 <term><parameter>name</parameter></term> 3433 <listitem><para>The name of the program to kill.</para></listitem> 3434 </varlistentry> 3435 </variablelist> 3436 3437 </sect3> 3438 3439 <sect3 id=absolute xreflabel="absolute procedure"> 3440 <title>Absolute Procedure</title> 3441 3442 <para>This procedure takes the relative <emphasis>path</emphasis>, 3443 and converts it to an absolute path.</para> 3444 3445 <funcsynopsis role="tcl"> 3446 <funcdef><function>absolute</function></funcdef> 3447 <paramdef><parameter>path</parameter></paramdef> 3448 </funcsynopsis> 3449 <variablelist> 3450 <varlistentry> 3451 <term><parameter>path</parameter></term> 3452 <listitem><para>The path to convert.</para></listitem> 3453 </varlistentry> 3454 </variablelist> 3455 </sect3> 3456 3457 <sect3 id=psource xreflabel="psource procedure"> 3458 <title>Psource Procedure</title> 3459 3460 <para>This sources the file <emphasis>filename</emphasis>, and traps 3461 all errors. It also ignores all extraneous output. If there was an 3462 error it returns a <emphasis>1</emphasis>, otherwise it returns a 3463 <emphasis>0</emphasis>.</para> 3464 3465 <funcsynopsis role="tcl"> 3466 <funcdef><function>psource</function></funcdef> 3467 <paramdef><parameter>file</parameter></paramdef> 3468 </funcsynopsis> 3469 <variablelist> 3470 <varlistentry> 3471 <term><parameter>filename</parameter></term> 3472 <listitem><para>The filename to Tcl script to 3473 source.</para></listitem> 3474 </varlistentry> 3475 </variablelist> 3476 </sect3> 3477 3478 <sect3 id=runtestfilep xreflabel="runtest_file_p procedure"> 3479 <title>Runtest_file_p Procedure</title> 3480 3481 <para>Search <emphasis>runtest</emphasis>s for 3482 <emphasis>testcase</emphasis> and return <emphasis>1</emphasis> if 3483 found, <emphasis>0</emphasis> if not. <emphasis>runtests</emphasis> 3484 is a list of two elements. The first is a copy of what was on 3485 the right side of the <emphasis>=</emphasis> if 3486 <programlisting>foo.exp="..."</programlisting>" was specified, or 3487 an empty string if no such argument is present. The second is the 3488 pathname of the current testcase under consideration. This is used 3489 by tools like compilers where each testcase is a file.</para> 3490 3491 <funcsynopsis role="tcl"> 3492 <funcdef><function>runtest_file_p</function></funcdef> 3493 <paramdef><parameter>runtests</parameter> 3494 <parameter>testcase</parameter></paramdef> 3495 </funcsynopsis> 3496 <variablelist> 3497 <varlistentry> 3498 <term><parameter>runtests</parameter></term> 3499 <listitem><para>The list of patterns to compare against. 3500 </para></listitem> 3501 </varlistentry> 3502 <varlistentry> 3503 <term><parameter>testcase</parameter></term> 3504 <listitem><para>The test case filename.</para></listitem> 3505 </varlistentry> 3506 </variablelist> 3507 </sect3> 3508 3509 <sect3 id=diff xreflabel="diff procedure"> 3510 <title>Diff Procedure</title> 3511 3512 <para>Compares the two files and returns a <emphasis>1</emphasis> if 3513 they match, or a <emphasis>0</emphasis> if they don't. If 3514 <symbol>verbose</symbol> is set, then it'll print the differences to 3515 the screen.</para> 3516 3517 <funcsynopsis role="tcl"> 3518 <funcdef><function>diff</function></funcdef> 3519 <paramdef><parameter>file_1</parameter> 3520 <parameter>file_2</parameter></paramdef> 3521 </funcsynopsis> 3522 <variablelist> 3523 <varlistentry> 3524 <term><parameter>file_1</parameter></term> 3525 <listitem><para>The first file to compare.</para></listitem> 3526 </varlistentry> 3527 <varlistentry> 3528 <term><parameter>file_2</parameter></term> 3529 <listitem><para>The second file to compare.</para></listitem> 3530 </varlistentry> 3531 </variablelist> 3532 </sect3> 3533 3534 <sect3 id=setenv xreflabel="setenv procedure"> 3535 <title>Setenv Procedure</title> 3536 3537 <para>Sets the environment variable <emphasis>var</emphasis> to the 3538 value <emphasis>val</emphasis>.</para> 3539 3540 <funcsynopsis role="tcl"> 3541 <funcdef><function>setenv</function></funcdef> 3542 <paramdef><parameter>var</parameter> 3543 <parameter>val</parameter></paramdef> 3544 </funcsynopsis> 3545 <variablelist> 3546 <varlistentry> 3547 <term><parameter>var</parameter></term> 3548 <listitem><para>The environment variable to set.</para></listitem> 3549 </varlistentry> 3550 <varlistentry> 3551 <term><parameter>val</parameter></term> 3552 <listitem><para>The value to set the variable to.</para></listitem> 3553 </varlistentry> 3554 </variablelist> 3555 3556 </sect3> 3557 <sect3 id=unsetenv xreflabel="unsetenv procedure"> 3558 <title>unsetenv Procedure</title> 3559 3560 <para>Unsets the environment variable 3561 <emphasis>var</emphasis>.</para> 3562 3563 <funcsynopsis role="tcl"> 3564 <funcdef><function>unsetenv</function></funcdef> 3565 <paramdef><parameter>var</parameter></paramdef> 3566 </funcsynopsis> 3567 <variablelist> 3568 <varlistentry> 3569 <term><parameter>var</parameter></term> 3570 <listitem><para>The environment variable to 3571 unset.</para></listitem> 3572 </varlistentry> 3573 </variablelist> 3574 </sect3> 3575 3576 <sect3 id=getenv xreflabel="getenv procedure"> 3577 <title>Getenv Procedure</title> 3578 3579 <para>Returns the value of <emphasis>var</emphasis> in the 3580 environment if it exists, otherwise it returns NULL.</para> 3581 3582 <funcsynopsis role="tcl"> 3583 <funcdef><function>getenv</function></funcdef> 3584 <paramdef><parameter>var</parameter></paramdef> 3585 </funcsynopsis> 3586 <variablelist> 3587 <varlistentry> 3588 <term><parameter>var</parameter></term> 3589 <listitem><para>The environment variable to get the value 3590 of.</para></listitem> 3591 </varlistentry> 3592 </variablelist> 3593 3594 </sect3> 3595 <sect3 id=prunesystemcrud xreflabel="prune_system_crud procedure"> 3596 <title>Prune_system_crud Procedure</title> 3597 3598 <para>For system <emphasis>system</emphasis>, delete text the host or 3599 target operating system might issue that will interfere with pattern 3600 matching of program output in <emphasis>text</emphasis>. An example 3601 is the message that is printed if a shared library is out of 3602 date.</para> 3603 3604 <funcsynopsis role="tcl"> 3605 <funcdef><function>prune_system_crud</function></funcdef> 3606 <paramdef><parameter>system</parameter> 3607 <parameter>test</parameter></paramdef> 3608 </funcsynopsis> 3609 <variablelist> 3610 <varlistentry> 3611 <term><parameter>system</parameter></term> 3612 <listitem><para>The system error messages to look for to screen out 3613 .</para></listitem> 3614 </varlistentry> 3615 <varlistentry> 3616 <term><parameter>text</parameter></term> 3617 <listitem><para>The Tcl variable containing the 3618 text.</para></listitem> 3619 </varlistentry> 3620 </variablelist> 3621 </sect3> 3622 3623 </sect2> 3624 3625 <sect2 id=libgloss xreflabel="Libgloss"> 3626 <title>Libgloss, A Free BSP</title> 3627 3628 <para>Libgloss is a free <firstterm>BSP</firstterm> (Board Support 3629 Package) commonly used with GCC and G++ to produce a fully linked 3630 executable image for an embedded systems.</para> 3631 3632 <sect3 id=libglosslinkflags xreflabel="libgloss_link_flags procedure"> 3633 <title>Libgloss_link_flags Procedure</title> 3634 3635 <para></para> 3636 3637 <funcsynopsis role="tcl"> 3638 <funcdef><function>libgloss_link_flags</function></funcdef> 3639 <paramdef><parameter>args</parameter></paramdef> 3640 </funcsynopsis> 3641 <variablelist> 3642 <varlistentry> 3643 <term><parameter>args</parameter></term> 3644 <listitem><para></para></listitem> 3645 </varlistentry> 3646 </variablelist> 3647 </sect3> 3648 3649 <sect3 id=libglossincludeflags xreflabel="libgloss_include_flags 3650 procedure"> 3651 <title>Libgloss_include_flags Procedure</title> 3652 3653 <para></para> 3654 3655 <funcsynopsis role="tcl"> 3656 <funcdef><function>libgloss_include_flags</function></funcdef> 3657 <paramdef><parameter>args</parameter></paramdef> 3658 </funcsynopsis> 3659 <variablelist> 3660 <varlistentry> 3661 <term><parameter>args</parameter></term> 3662 <listitem><para></para></listitem> 3663 </varlistentry> 3664 </variablelist> 3665 </sect3> 3666 3667 <sect3 id=newliblinkflags xreflabel="newlib_link_flags procedure"> 3668 <title>Newlib_link_flags Procedure</title> 3669 3670 <para></para> 3671 3672 <funcsynopsis role="tcl"> 3673 <funcdef><function>newlib_link_flags</function></funcdef> 3674 <paramdef><parameter>args</parameter></paramdef> 3675 </funcsynopsis> 3676 <variablelist> 3677 <varlistentry> 3678 <term><parameter>args</parameter></term> 3679 <listitem><para></para></listitem> 3680 </varlistentry> 3681 </variablelist> 3682 </sect3> 3683 3684 <sect3 id=newlibincludeflags xreflabel="newlib_include_flags 3685 procedure"> 3686 <title>Newlib_include_flags Procedure</title> 3687 3688 <para></para> 3689 3690 <funcsynopsis role="tcl"> 3691 <funcdef><function>newlib_include_flags</function></funcdef> 3692 <paramdef><parameter>args</parameter></paramdef> 3693 </funcsynopsis> 3694 <variablelist> 3695 <varlistentry> 3696 <term><parameter>args</parameter></term> 3697 <listitem><para></para></listitem> 3698 </varlistentry> 3699 </variablelist> 3700 </sect3> 3701 3702 <sect3 id=libioincludeflags xreflabel="libio_include_flags 3703 procedure"> 3704 <title>Libio_include_flags Procedure</title> 3705 3706 <para></para> 3707 3708 <funcsynopsis role="tcl"> 3709 <funcdef><function>libio_include_flags</function></funcdef> 3710 <paramdef><parameter>args</parameter></paramdef> 3711 </funcsynopsis> 3712 <variablelist> 3713 <varlistentry> 3714 <term><parameter>args</parameter></term> 3715 <listitem><para></para></listitem> 3716 </varlistentry> 3717 </variablelist> 3718 </sect3> 3719 3720 <sect3 id=libiolinkflags xreflabel="libio_link_flags procedure"> 3721 <title>Libio_link_flags Procedure</title> 3722 3723 <para></para> 3724 3725 <funcsynopsis role="tcl"> 3726 <funcdef><function>libio_link_flags</function></funcdef> 3727 <paramdef><parameter>args</parameter></paramdef> 3728 </funcsynopsis> 3729 <variablelist> 3730 <varlistentry> 3731 <term><parameter>args</parameter></term> 3732 <listitem><para></para></listitem> 3733 </varlistentry> 3734 </variablelist> 3735 </sect3> 3736 3737 <sect3 id=gxxincludeflags xreflabel="g++_include_flags procedure"> 3738 <title>G++_include_flags Procedure</title> 3739 3740 <para></para> 3741 3742 <funcsynopsis role="tcl"> 3743 <funcdef><function>g++_include_flags</function></funcdef> 3744 <paramdef><parameter>args</parameter></paramdef> 3745 </funcsynopsis> 3746 <variablelist> 3747 <varlistentry> 3748 <term><parameter>args</parameter></term> 3749 <listitem><para></para></listitem> 3750 </varlistentry> 3751 </variablelist> 3752 </sect3> 3753 3754 <sect3 id=gxxlinkflags xreflabel="g++_link_flags procedure"> 3755 <title>G++_link_flags Procedure</title> 3756 3757 <para></para> 3758 3759 <funcsynopsis role="tcl"> 3760 <funcdef><function>g++_link_flags</function></funcdef> 3761 <paramdef><parameter>args</parameter></paramdef> 3762 </funcsynopsis> 3763 <variablelist> 3764 <varlistentry> 3765 <term><parameter>args</parameter></term> 3766 <listitem><para></para></listitem> 3767 </varlistentry> 3768 </variablelist> 3769 </sect3> 3770 3771 <sect3 id=libstdcxxincludeflags xreflabel="libstdc++_include_flags 3772 procedure"> 3773 <title>Libstdc++_include_flags Procedure</title> 3774 3775 <para></para> 3776 3777 <funcsynopsis role="tcl"> 3778 <funcdef><function>libstdc++_include_flags</function></funcdef> 3779 <paramdef><parameter>args</parameter></paramdef> 3780 </funcsynopsis> 3781 <variablelist> 3782 <varlistentry> 3783 <term><parameter>args</parameter></term> 3784 <listitem><para></para></listitem> 3785 </varlistentry> 3786 </variablelist> 3787 </sect3> 3788 3789 <sect3 id=libstdcxxlinkflags xreflabel="libstdc++_link_flags 3790 procedure"> 3791 <title>Libstdc++_link_flags Procedure</title> 3792 3793 <para></para> 3794 3795 <funcsynopsis role="tcl"> 3796 <funcdef><function>libstdc++_link_flags</function></funcdef> 3797 <paramdef><parameter>args</parameter></paramdef> 3798 </funcsynopsis> 3799 <variablelist> 3800 <varlistentry> 3801 <term><parameter>args</parameter></term> 3802 <listitem><para></para></listitem> 3803 </varlistentry> 3804 </variablelist> 3805 </sect3> 3806 3807 <sect3 id=getmultilibs xreflabel="get_multilibs procedure"> 3808 <title>Get_multilibs Procedure</title> 3809 3810 <para></para> 3811 3812 <funcsynopsis role="tcl"> 3813 <funcdef><function>get_multilibs</function></funcdef> 3814 <paramdef><parameter>args</parameter></paramdef> 3815 </funcsynopsis> 3816 <variablelist> 3817 <varlistentry> 3818 <term><parameter>args</parameter></term> 3819 <listitem><para></para></listitem> 3820 </varlistentry> 3821 </variablelist> 3822 </sect3> 3823 3824 <sect3 id=findbinutilsprog xreflabel="find_binutils_prog procedure"> 3825 <title>Find_binutils_prog Procedure</title> 3826 3827 <para></para> 3828 3829 <funcsynopsis role="tcl"> 3830 <funcdef><function>find_binutils_prog</function></funcdef> 3831 <paramdef><parameter>name</parameter></paramdef> 3832 </funcsynopsis> 3833 <variablelist> 3834 <varlistentry> 3835 <term><parameter>name</parameter></term> 3836 <listitem><para></para></listitem> 3837 </varlistentry> 3838 </variablelist> 3839 </sect3> 3840 3841 <sect3 id=findgcc xreflabel="find_gcc procedure"> 3842 <title>Find_gcc Procedure</title> 3843 3844 <para></para> 3845 3846 <funcsynopsis role="tcl"> 3847 <funcdef><function>find_gcc</function></funcdef> 3848 <paramdef><parameter></parameter></paramdef> 3849 </funcsynopsis> 3850 </sect3> 3851 3852 <sect3 id=findgcj xreflabel="find_gcj procedure"> 3853 <title>Find_gcj Procedure</title> 3854 3855 <para></para> 3856 3857 <funcsynopsis role="tcl"> 3858 <funcdef><function>find_gcj</function></funcdef> 3859 <paramdef><parameter></parameter></paramdef> 3860 </funcsynopsis> 3861 </sect3> 3862 3863 <sect3 id=findgxx xreflabel="find_g++ procedure"> 3864 <title>Find_g++ Procedure</title> 3865 3866 <para></para> 3867 3868 <funcsynopsis role="tcl"> 3869 <funcdef><function>find_g++</function></funcdef> 3870 <paramdef><parameter></parameter></paramdef> 3871 </funcsynopsis> 3872 </sect3> 3873 3874 <sect3 id=findg77 xreflabel="find_g77 procedure"> 3875 <title>Find_g77 Procedure</title> 3876 3877 <para></para> 3878 3879 <funcsynopsis role="tcl"> 3880 <funcdef><function>find_g77</function></funcdef> 3881 <paramdef><parameter></parameter></paramdef> 3882 </funcsynopsis> 3883 </sect3> 3884 3885 <sect3 id=processmultiliboptions xreflabel="process_multilib_options 3886 procedure"> 3887 <title>Process_multilib_options Procedure</title> 3888 3889 <para></para> 3890 3891 <funcsynopsis role="tcl"> 3892 <funcdef><function>process_multilib_options</function></funcdef> 3893 <paramdef><parameter>args</parameter></paramdef> 3894 </funcsynopsis> 3895 <variablelist> 3896 <varlistentry> 3897 <term><parameter>args</parameter></term> 3898 <listitem><para></para></listitem> 3899 </varlistentry> 3900 </variablelist> 3901 </sect3> 3902 3903 <sect3 id=addmultiliboption xreflabel="add_multilib_option 3904 procedure"> 3905 <title>Add_multilib_option Procedure</title> 3906 3907 <para></para> 3908 3909 <funcsynopsis role="tcl"> 3910 <funcdef><function>add_multilib_option</function></funcdef> 3911 <paramdef><parameter>args</parameter></paramdef> 3912 </funcsynopsis> 3913 <variablelist> 3914 <varlistentry> 3915 <term><parameter>args</parameter></term> 3916 <listitem><para></para></listitem> 3917 </varlistentry> 3918 </variablelist> 3919 </sect3> 3920 3921 <sect3 id=findgas xreflabel="find_gas procedure"> 3922 <title>Find_gas Procedure</title> 3923 3924 <para></para> 3925 3926 <funcsynopsis role="tcl"> 3927 <funcdef><function>find_gas</function></funcdef> 3928 <paramdef><parameter></parameter></paramdef> 3929 </funcsynopsis> 3930 </sect3> 3931 3932 <sect3 id=findld xreflabel="find_ld procedure"> 3933 <title>Find_ld Procedure</title> 3934 3935 <para></para> 3936 3937 <funcsynopsis role="tcl"> 3938 <funcdef><function>find_ld</function></funcdef> 3939 <paramdef><parameter></parameter></paramdef> 3940 </funcsynopsis> 3941 </sect3> 3942 3943 <sect3 id=buildwrapper xreflabel="build_wrapper procedure"> 3944 <title>Build_wrapper Procedure</title> 3945 3946 <para></para> 3947 3948 <funcsynopsis role="tcl"> 3949 <funcdef><function>build_wrapper</function></funcdef> 3950 <paramdef><parameter>gluefile</parameter></paramdef> 3951 </funcsynopsis> 3952 <variablelist> 3953 <varlistentry> 3954 <term><parameter>gluefile</parameter></term> 3955 <listitem><para></para></listitem> 3956 </varlistentry> 3957 </variablelist> 3958 </sect3> 3959 3960 <sect3 id=winsupincludeflags xreflabel="winsup_include_flags 3961 procedure"> 3962 <title>Winsup_include_flags Procedure</title> 3963 3964 <para></para> 3965 3966 <funcsynopsis role="tcl"> 3967 <funcdef><function>winsup_include_flags</function></funcdef> 3968 <paramdef><parameter>args</parameter></paramdef> 3969 </funcsynopsis> 3970 <variablelist> 3971 <varlistentry> 3972 <term><parameter>args</parameter></term> 3973 <listitem><para></para></listitem> 3974 </varlistentry> 3975 </variablelist> 3976 </sect3> 3977 3978 <sect3 id=winsuplinkflags xreflabel="winsup_link_flags procedure"> 3979 <title>Winsup_link_flags Procedure</title> 3980 3981 <para></para> 3982 3983 <funcsynopsis role="tcl"> 3984 <funcdef><function>winsup_link_flags</function></funcdef> 3985 <paramdef><parameter>args</parameter></paramdef> 3986 </funcsynopsis> 3987 <variablelist> 3988 <varlistentry> 3989 <term><parameter>args</parameter></term> 3990 <listitem><para></para></listitem> 3991 </varlistentry> 3992 </variablelist> 3993 </sect3> 3994 </sect2> 3995 3996 <sect2 id=debugprocs xreflabel="Debugging Procedures"> 3997 <title>Procedures for debugging your Tcl code.</title> 3998 3999 <para><filename>lib/debugger.exp</filename>defines these utility 4000 procedures:</para> 4001 4002 <sect3 id=dumpvars xreflabel="dumpvars procedure"> 4003 <title>Dumpvars Procedure</title> 4004 4005 <para>This takes a csh style regular expression (glob rules) and prints 4006 the values of the global variable names that match. It is abbreviated 4007 as <emphasis>dv</emphasis>.</para> 4008 4009 <funcsynopsis role="tcl"> 4010 <funcdef><function>dumpvars</function></funcdef> 4011 <paramdef><parameter>vars</parameter></paramdef> 4012 </funcsynopsis> 4013 <variablelist> 4014 <varlistentry> 4015 <term><parameter>vars</parameter></term> 4016 <listitem><para>The variables to dump.</para></listitem> 4017 </varlistentry> 4018 </variablelist> 4019 </sect3> 4020 4021 <sect3 id=dumplocals xreflabel="dumplocals procedure"> 4022 <title>Dumplocals Procedure</title> 4023 4024 <para>This takes a csh style regular expression (glob rules) and 4025 prints the values of the local variable names that match. It is 4026 abbreviated as <emphasis>dl</emphasis>.</para> 4027 4028 <funcsynopsis role="tcl"> 4029 <funcdef><function>dumplocals</function></funcdef> 4030 <paramdef><parameter>args</parameter></paramdef> 4031 </funcsynopsis> 4032 <variablelist> 4033 <varlistentry> 4034 <term><parameter>args</parameter></term> 4035 <listitem><para></para></listitem> 4036 </varlistentry> 4037 </variablelist> 4038 </sect3> 4039 4040 <sect3 id=dumprocs xreflabel="dumprocs procedure"> 4041 <title>Dumprocs Procedure</title> 4042 4043 <para>This takes a csh style regular expression (glob rules) and 4044 prints the body of all procs that match. It is abbreviated as 4045 <emphasis>dp</emphasis>.</para> 4046 4047 <funcsynopsis role="tcl"> 4048 <funcdef><function>dumprocs</function></funcdef> 4049 <paramdef><parameter>pattern</parameter></paramdef> 4050 </funcsynopsis> 4051 <variablelist> 4052 <varlistentry> 4053 <term><parameter>pattern</parameter></term> 4054 <listitem><para>The csh "glob" style pattern to look 4055 for.</para></listitem> 4056 </varlistentry> 4057 </variablelist> 4058 </sect3> 4059 4060 <sect3 id=dumpwatch xreflabel="dumpwatch procedure"> 4061 <title>Dumpwatch Procedure</title> 4062 4063 <para>This takes a csh style regular expression (glob rules) and 4064 prints all the watchpoints. It is abbreviated as 4065 <emphasis>dw</emphasis>.</para> 4066 4067 <funcsynopsis role="tcl"> 4068 <funcdef><function>dumpwatch</function></funcdef> 4069 <paramdef><parameter>pattern</parameter></paramdef> 4070 </funcsynopsis> 4071 <variablelist> 4072 <varlistentry> 4073 <term><parameter>pattern</parameter></term> 4074 <listitem><para>The csh "glob" style pattern to look 4075 for.</para></listitem> 4076 </varlistentry> 4077 </variablelist> 4078 </sect3> 4079 4080 <sect3 id=watcharray xreflabel="watcharray procedure"> 4081 <title>Watcharray Procedure</title> 4082 4083 <para></para> 4084 4085 <funcsynopsis role="tcl"> 4086 <funcdef><function>watcharray</function></funcdef> 4087 <paramdef><parameter>element</parameter> 4088 <parameter>type</parameter></paramdef> 4089 </funcsynopsis> 4090 <variablelist> 4091 <varlistentry> 4092 <term><parameter>type</parameter></term> 4093 <listitem><para>The csh "glob" style pattern to look 4094 for.</para></listitem> 4095 </varlistentry> 4096 </variablelist> 4097 </sect3> 4098 4099 <sect3 id=watchvar xreflabel="watchvar procedure"> 4100 <title>Watchvar Procedure</title> 4101 4102 <para></para> 4103 4104 <funcsynopsis role="tcl"> 4105 <funcdef><function>watchvar</function></funcdef> 4106 <paramdef><parameter>var</parameter> 4107 <parameter>type</parameter></paramdef> 4108 </funcsynopsis> 4109 <variablelist> 4110 <varlistentry> 4111 <term><parameter></parameter></term> 4112 <listitem><para></para></listitem> 4113 </varlistentry> 4114 </variablelist> 4115 </sect3> 4116 4117 <sect3 id=watchunset xreflabel="watchunset procedure"> 4118 <title>Watchunset Procedure</title> 4119 4120 <para>This breaks program execution when the variable 4121 <symbol>var</symbol> is unset. It is abbreviated as 4122 <emphasis>wu</emphasis>.</para> 4123 4124 <funcsynopsis role="tcl"> 4125 <funcdef><function>watchunset</function></funcdef> 4126 <paramdef><parameter>arg</parameter></paramdef> 4127 </funcsynopsis> 4128 <variablelist> 4129 <varlistentry> 4130 <term><parameter>args</parameter></term> 4131 <listitem><para></para></listitem> 4132 </varlistentry> 4133 </variablelist> 4134 </sect3> 4135 4136 <sect3 id=watchwrite xreflabel="watchwrite procedure"> 4137 <title>Watchwrite Procedure</title> 4138 4139 <para>This breaks program execution when the variable 4140 <symbol>var</symbol> is written. It is abbreviated as 4141 <emphasis>ww</emphasis>.</para> 4142 4143 <funcsynopsis role="tcl"> 4144 <funcdef><function>watchwrite</function></funcdef> 4145 <paramdef><parameter>var</parameter></paramdef> 4146 </funcsynopsis> 4147 <variablelist> 4148 <varlistentry> 4149 <term><parameter>var</parameter></term> 4150 <listitem><para>The variable to watch.</para></listitem> 4151 </varlistentry> 4152 </variablelist> 4153 </sect3> 4154 4155 <sect3 id=watchread xreflabel="watchread procedure"> 4156 <title>Watchread Procedure</title> 4157 4158 <para>This breaks program execution when the variable 4159 <symbol>var</symbol> is read. It is abbreviated as 4160 <emphasis>wr</emphasis>.</para> 4161 4162 <funcsynopsis role="tcl"> 4163 <funcdef><function>watchread</function></funcdef> 4164 <paramdef><parameter>var</parameter></paramdef> 4165 </funcsynopsis> 4166 <variablelist> 4167 <varlistentry> 4168 <term><parameter>var</parameter></term> 4169 <listitem><para>The variable to watch.</para></listitem> 4170 </varlistentry> 4171 </variablelist> 4172 </sect3> 4173 4174 <sect3 id=watchdel xreflabel="watchdel procedure"> 4175 <title>Watchdel Procedure</title> 4176 4177 <para>This deletes a the watchpoint from the watch list. It is 4178 abbreviated as <emphasis>wd</emphasis>.</para> 4179 4180 <funcsynopsis role="tcl"> 4181 <funcdef><function>watchdel</function></funcdef> 4182 <paramdef><parameter>args</parameter></paramdef> 4183 </funcsynopsis> 4184 <variablelist> 4185 <varlistentry> 4186 <term><parameter>args</parameter></term> 4187 <listitem><para></para></listitem> 4188 </varlistentry> 4189 </variablelist> 4190 </sect3> 4191 4192 <sect3 id=print xreflabel="print procedure"> 4193 <title>Print Procedure</title> 4194 4195 <para>This prints the value of the variable 4196 <parameter>var</parameter>. It is abbreviated as 4197 <emphasis>p</emphasis>.</para> 4198 4199 <funcsynopsis role="tcl"> 4200 <funcdef><function>print</function></funcdef> 4201 <paramdef><parameter>var</parameter></paramdef> 4202 </funcsynopsis> 4203 <variablelist> 4204 <varlistentry> 4205 <term><parameter>var</parameter></term> 4206 <listitem><para></para></listitem> 4207 </varlistentry> 4208 </variablelist> 4209 </sect3> 4210 4211 <sect3 id=quit xreflabel="quit procedure"> 4212 <title>Quit Procedure</title> 4213 4214 <para>This makes runtest exit. It is abbreviated as 4215 <emphasis>q</emphasis>.</para> 4216 4217 <funcsynopsis role="tcl"> 4218 <funcdef><function>quit</function></funcdef> 4219 <paramdef><parameter></parameter></paramdef> 4220 </funcsynopsis> 4221 <variablelist> 4222 <varlistentry> 4223 <term><parameter></parameter></term> 4224 <listitem><para></para></listitem> 4225 </varlistentry> 4226 </variablelist> 4227 </sect3> 4228 4229 </sect2> 4230 4231 </sect1> 4232 4233 <sect1 id=filemap> 4234 <title>File Map</title> 4235 4236 <para>This is a map of the files in DejaGnu.</para> 4237 4238 <itemizedlist> 4239 <listitem><para>runtest</para></listitem> 4240 <listitem><para>runtest.exp</para></listitem> 4241 <listitem><para>stub-loader.c</para></listitem> 4242 <listitem><para>testglue.c</para></listitem> 4243 <listitem><para>config</para></listitem> 4244 <listitem><para>baseboards</para></listitem> 4245 <listitem><para>lib/debugger.exp</para></listitem> 4246 <listitem><para>lib/dg.exp</para></listitem> 4247 <listitem><para>lib/framework.exp</para></listitem> 4248 <listitem><para>lib/ftp.exp</para></listitem> 4249 <listitem><para>lib/kermit.exp</para></listitem> 4250 <listitem><para>lib/libgloss.exp</para></listitem> 4251 <listitem><para>lib/mondfe.exp</para></listitem> 4252 <listitem><para>lib/remote.exp</para></listitem> 4253 <listitem><para>lib/rlogin.exp</para></listitem> 4254 <listitem><para>lib/rsh.exp</para></listitem> 4255 <listitem><para>lib/standard.exp</para></listitem> 4256 <listitem><para>lib/target.exp</para></listitem> 4257 <listitem><para>lib/targetdb.exp</para></listitem> 4258 <listitem><para>lib/telnet.exp</para></listitem> 4259 <listitem><para>lib/tip.exp</para></listitem> 4260 <listitem><para>lib/util-defs.exp</para></listitem> 4261 <listitem><para>lib/utils.exp</para></listitem> 4262 <listitem><para>lib/xsh.exp</para></listitem> 4263 <listitem><para>lib/dejagnu.exp</para></listitem> 4264 </itemizedlist> 4265 4266 </sect1> 4267 4268</chapter> 4269 4270<chapter id=unittestapi xreflabel="Unit Testing API"> 4271 <title>Unit Testing API</title> 4272 4273 <sect1 id=cunit xreflabel="C Unit Testing API"> 4274 <title>C Unit Testing API</title> 4275 4276 <para>All of the functions that take a 4277 <parameter>msg</parameter> parameter use a C char * that is 4278 the message to be dislayed. There currently is no support for 4279 variable length arguments.</para> 4280 4281 4282 <sect2 id=passfunc xreflabel="pass function"> 4283 <title>Pass Function</title> 4284 4285 <para>This prints a message for a successful test 4286 completion.</para> 4287 4288 <funcsynopsis role="C"> 4289 <funcdef><function>pass</function></funcdef> 4290 <paramdef><parameter>msg</parameter></paramdef> 4291 </funcsynopsis> 4292 4293 </sect2> 4294 4295 <sect2 id=failfunc xreflabel="fail function"> 4296 <title>Fail Function</title> 4297 4298 <para>This prints a message for an unsuccessful test 4299 completion.</para> 4300 4301 <funcsynopsis role="C"> 4302 <funcdef><function>fail</function></funcdef> 4303 <paramdef><parameter>msg</parameter></paramdef> 4304 </funcsynopsis> 4305 4306 </sect2> 4307 4308 <sect2 id=untestedfunc xreflabel="untested function"> 4309 <title>Untested Function</title> 4310 4311 <para>This prints a message for an test case that isn't run 4312 for some technical reason.</para> 4313 4314 <funcsynopsis role="C"> 4315 <funcdef><function>untested</function></funcdef> 4316 <paramdef><parameter>msg</parameter></paramdef> 4317 </funcsynopsis> 4318 </sect2> 4319 4320 <sect2 id=unresolvedfunc xreflabel="unresolved function"> 4321 <title>Unresolved Function</title> 4322 4323 <para>This prints a message for an test case that is run, 4324 but there is no clear result. These output states require a 4325 human to look over the results to determine what happened. 4326 </para> 4327 4328 <funcsynopsis role="C"> 4329 <funcdef><function>unresolved</function></funcdef> 4330 <paramdef><parameter>msg</parameter></paramdef> 4331 </funcsynopsis> 4332 </sect2> 4333 4334 <sect2 id=totalsfunc xreflabel="totals function"> 4335 <title>Totals Function</title> 4336 4337 <para>This prints out the total numbers of all the test 4338 state outputs.</para> 4339 4340 <funcsynopsis role="C"> 4341 <funcdef><function>totals</function></funcdef> 4342 <paramdef><parameter></parameter></paramdef> 4343 </funcsynopsis> 4344 </sect2> 4345 4346 </sect1> 4347 4348 <sect1 id=cppunit xreflabel="C++ Unit Testing API"> 4349 <title>C++ Unit Testing API</title> 4350 4351 <para>All of the methods that take a 4352 <parameter>msg</parameter> parameter use a C char * 4353 or STL string, that is the message to be 4354 dislayed. There currently is no support for variable 4355 length arguments.</para> 4356 4357 <sect2 id=passmeth xreflabel="pass method"> 4358 <title>Pass Method</title> 4359 4360 <para>This prints a message for a successful test 4361 completion.</para> 4362 4363 <funcsynopsis role="C++"> 4364 <funcdef><function>TestState::pass</function></funcdef> 4365 <paramdef><parameter>msg</parameter></paramdef> 4366 </funcsynopsis> 4367 </sect2> 4368 4369 <sect2 id=failmeth xreflabel="fail method"> 4370 <title>Fail Method</title> 4371 4372 <para>This prints a message for an unsuccessful test 4373 completion.</para> 4374 4375 <funcsynopsis role="C++"> 4376 <funcdef><function>TestState::fail</function></funcdef> 4377 <paramdef><parameter>msg</parameter></paramdef> 4378 </funcsynopsis> 4379 </sect2> 4380 4381 <sect2 id=untestedmeth xreflabel="untested method"> 4382 <title>Untested Method</title> 4383 4384 <para>This prints a message for an test case that isn't run 4385 for some technical reason.</para> 4386 4387 <funcsynopsis role="C++"> 4388 <funcdef><function>TestState::untested</function></funcdef> 4389 <paramdef><parameter>msg</parameter></paramdef> 4390 </funcsynopsis> 4391 </sect2> 4392 4393 <sect2 id=unresolvedmeth xreflabel="unresolved method"> 4394 <title>Unresolved Method</title> 4395 4396 <para>This prints a message for an test case that is run, 4397 but there is no clear result. These output states require a 4398 human to look over the results to determine what happened. 4399 </para> 4400 4401 <funcsynopsis role="C++"> 4402 <funcdef><function>TestState::unresolved</function></funcdef> 4403 <paramdef><parameter>msg</parameter></paramdef> 4404 </funcsynopsis> 4405 </sect2> 4406 4407 <sect2 id=totalsmeth xreflabel="totals method"> 4408 <title>Totals Method</title> 4409 4410 <para>This prints out the total numbers of all the test 4411 state outputs.</para> 4412 4413 <funcsynopsis role="C++"> 4414 <funcdef><function>TestState::totals</function></funcdef> 4415 <paramdef><parameter></parameter></paramdef> 4416 </funcsynopsis> 4417 </sect2> 4418 4419 </sect1> 4420 4421</chapter> 4422 4423<!-- Keep this comment at the end of the file 4424Local variables: 4425mode: sgml 4426sgml-omittag:t 4427sgml-shorttag:t 4428sgml-namecase-general:t 4429sgml-general-insert-case:lower 4430sgml-minimize-attributes:nil 4431sgml-always-quote-attributes:t 4432sgml-indent-step:1 4433sgml-indent-data:nil 4434sgml-parent-document:nil 4435sgml-exposed-tags:nil 4436sgml-local-catalogs:nil 4437sgml-local-ecat-files:nil 4438End: 4439--> 4440