2 '\" Copyright (c) 1993 The Regents of the University of California.
3 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
5 '\" See the file "license.terms" for information on usage and redistribution
6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
8 .TH open n 8.3 Tcl "Tcl Built-In Commands"
9 .\" The -*- nroff -*- definitions below are for supplemental macros used
10 .\" in Tcl/Tk manual entries.
12 .\" .AP type name in/out ?indent?
13 .\" Start paragraph describing an argument to a library procedure.
14 .\" type is type of argument (int, etc.), in/out is either "in", "out",
15 .\" or "in/out" to describe whether procedure reads or modifies arg,
16 .\" and indent is equivalent to second arg of .IP (shouldn't ever be
17 .\" needed; use .AS below instead)
20 .\" Give maximum sizes of arguments for setting tab stops. Type and
21 .\" name are examples of largest possible arguments that will be passed
22 .\" to .AP later. If args are omitted, default tab stops are used.
25 .\" Start box enclosure. From here until next .BE, everything will be
26 .\" enclosed in one large box.
29 .\" End of box enclosure.
32 .\" Begin code excerpt.
37 .\" .VS ?version? ?br?
38 .\" Begin vertical sidebar, for use in marking newly-changed parts
39 .\" of man pages. The first argument is ignored and used for recording
40 .\" the version when the .VS was added, so that the sidebars can be
41 .\" found and removed when they reach a certain age. If another argument
42 .\" is present, then a line break is forced before starting the sidebar.
45 .\" End of vertical sidebar.
48 .\" Begin an indented unfilled display.
51 .\" End of indented unfilled display.
54 .\" Start of list of standard options for a Tk widget. The manpage
55 .\" argument defines where to look up the standard options; if
56 .\" omitted, defaults to "options". The options follow on successive
57 .\" lines, in three columns separated by tabs.
60 .\" End of list of standard options for a Tk widget.
62 .\" .OP cmdName dbName dbClass
63 .\" Start of description of a specific option. cmdName gives the
64 .\" option's name as specified in the class command, dbName gives
65 .\" the option's name in the option database, and dbClass gives
66 .\" the option's class in the option database.
69 .\" Print arg1 underlined, then print arg2 normally.
72 .\" Print arg1 in quotes, then arg2 normally (for trailing punctuation).
75 .\" Print an open parenthesis, arg1 in quotes, then arg2 normally
76 .\" (for trailing punctuation) and then a closing parenthesis.
78 .\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
82 .\" # Start an argument description
86 . ie !"\\$2"" .TP \\n()Cu
91 \&\\$1 \\fI\\$2\\fP (\\$3)
104 .\" # define tabbing values for .AP
107 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
110 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
111 .nr )C \\n()Bu+\\w'(in/out)'u+2n
113 .AS Tcl_Interp Tcl_CreateInterp in/out
114 .\" # BS - start boxed text
115 .\" # ^y = starting y location
123 .if n \l'\\n(.lu\(ul'
126 .\" # BE - end boxed text (draw box now)
131 .ie n \l'\\n(^lu\(ul'
133 .\" Draw four-sided box normally, but don't draw top of
134 .\" box if the box started on an earlier page.
136 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
139 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
146 .\" # VS - start vertical sidebar
147 .\" # ^Y = starting y location
148 .\" # ^v = 1 (for troff; for nroff this doesn't matter)
152 .ie n 'mc \s12\(br\s0
155 .\" # VE - end of vertical sidebar
163 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
170 .\" # Special macro to handle page bottom: finish off current
171 .\" # box/sidebar if in box/sidebar mode, then invoked standard
172 .\" # page bottom macro.
179 .\" Draw three-sided box if this is the box's first page,
180 .\" draw two sides but no top otherwise.
181 .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
182 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
185 .nr ^x \\n(^tu+1v-\\n(^Yu
186 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
199 .\" # DS - begin display
205 .\" # DE - end display
211 .\" # SO - start of list of standard options
213 'ie '\\$1'' .ds So \\fBoptions\\fR
214 'el .ds So \\fB\\$1\\fR
215 .SH "STANDARD OPTIONS"
221 .\" # SE - end of list of standard options
226 See the \\*(So manual entry for details on the standard options.
228 .\" # OP - start of full description for a single option
233 Command-Line Name: \\fB\\$1\\fR
234 Database Name: \\fB\\$2\\fR
235 Database Class: \\fB\\$3\\fR
239 .\" # CS - begin code excerpt
245 .\" # CE - end code excerpt
250 .\" # UL - underline word
254 .\" # QW - apply quotation marks to word
256 .ie '\\*(lq'"' ``\\$1''\\$2
257 .\"" fix emacs highlighting
258 .el \\*(lq\\$1\\*(rq\\$2
260 .\" # PQ - apply parens and quotation marks to word
262 .ie '\\*(lq'"' (``\\$1''\\$2)\\$3
263 .\"" fix emacs highlighting
264 .el (\\*(lq\\$1\\*(rq\\$2)\\$3
266 .\" # QR - quoted range
268 .ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
269 .\"" fix emacs highlighting
270 .el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
272 .\" # MT - "empty" string
277 '\" Note: do not modify the .SH NAME line immediately below!
279 open \- Open a file-based or command pipeline channel
282 \fBopen \fIfileName\fR
284 \fBopen \fIfileName access\fR
286 \fBopen \fIfileName access permissions\fR
290 This command opens a file, serial port, or command pipeline and returns a
291 channel identifier that may be used in future invocations of commands like
292 \fBread\fR, \fBputs\fR, and \fBclose\fR.
293 If the first character of \fIfileName\fR is not \fB|\fR then
294 the command opens a file:
295 \fIfileName\fR gives the name of the file to open, and it must conform to the
296 conventions described in the \fBfilename\fR manual entry.
298 The \fIaccess\fR argument, if present, indicates the way in which the file
299 (or command pipeline) is to be accessed.
300 In the first form \fIaccess\fR may have any of the following values:
304 Open the file for reading only; the file must already exist. This is the
305 default value if \fIaccess\fR is not specified.
309 Open the file for both reading and writing; the file must
314 Open the file for writing only. Truncate it if it exists. If it does not
315 exist, create a new file.
319 Open the file for reading and writing. Truncate it if it exists.
320 If it does not exist, create a new file.
324 Open the file for writing only. If the file does not exist,
325 create a new empty file.
326 Set the file pointer to the end of the file prior to each write.
330 Open the file for reading and writing. If the file does not exist,
331 create a new empty file.
332 Set the initial access position to the end of the file.
334 All of the legal \fIaccess\fR values above may have the character
335 \fBb\fR added as the second or third character in the value to
336 indicate that the opened channel should be configured as if with the
337 \fBfconfigure\fR \fB\-translation binary\fR option, making the channel suitable for
338 reading or writing of binary data.
340 In the second form, \fIaccess\fR consists of a list of any of the
341 following flags, all of which have the standard POSIX meanings.
342 One of the flags must be either \fBRDONLY\fR, \fBWRONLY\fR or \fBRDWR\fR.
346 Open the file for reading only.
350 Open the file for writing only.
354 Open the file for both reading and writing.
358 Set the file pointer to the end of the file prior to each write.
362 Configure the opened channel with the \fB\-translation binary\fR option.
366 Create the file if it does not already exist (without this flag it
367 is an error for the file not to exist).
371 If \fBCREAT\fR is also specified, an error is returned if the
376 If the file is a terminal device, this flag prevents the file from
377 becoming the controlling terminal of the process.
381 Prevents the process from blocking while opening the file, and
382 possibly in subsequent I/O operations. The exact behavior of
383 this flag is system- and device-dependent; its use is discouraged
384 (it is better to use the \fBfconfigure\fR command to put a file
385 in nonblocking mode).
386 For details refer to your system documentation on the \fBopen\fR system
387 call's \fBO_NONBLOCK\fR flag.
391 If the file exists it is truncated to zero length.
393 If a new file is created as part of opening it, \fIpermissions\fR
394 (an integer) is used to set the permissions for the new file in
395 conjunction with the process's file mode creation mask.
396 \fIPermissions\fR defaults to 0666.
397 .SH "COMMAND PIPELINES"
399 If the first character of \fIfileName\fR is
402 remaining characters of \fIfileName\fR are treated as a list of arguments
403 that describe a command pipeline to invoke, in the same style as the
404 arguments for \fBexec\fR.
405 In this case, the channel identifier returned by \fBopen\fR may be used
406 to write to the command's input pipe or read from its output pipe,
407 depending on the value of \fIaccess\fR.
408 If write-only access is used (e.g. \fIaccess\fR is
410 then standard output for the pipeline is directed to the current standard
411 output unless overridden by the command.
412 If read-only access is used (e.g. \fIaccess\fR is
414 standard input for the pipeline is taken from the current standard
415 input unless overridden by the command.
416 The id of the spawned process is accessible through the \fBpid\fR
417 command, using the channel id returned by \fBopen\fR as argument.
419 If the command (or one of the commands) executed in the command
420 pipeline returns an error (according to the definition in \fBexec\fR),
421 a Tcl error is generated when \fBclose\fR is called on the channel
422 unless the pipeline is in non-blocking mode then no exit status is
423 returned (a silent \fBclose\fR with -blocking 0).
425 It is often useful to use the \fBfileevent\fR command with pipelines
426 so other processing may happen at the same time as running the command
428 .SH "SERIAL COMMUNICATIONS"
430 If \fIfileName\fR refers to a serial port, then the specified serial port
431 is opened and initialized in a platform-dependent manner. Acceptable
432 values for the \fIfileName\fR to use to open a serial port are described in
433 the PORTABILITY ISSUES section.
435 The \fBfconfigure\fR command can be used to query and set additional
436 configuration options specific to serial ports (where supported):
438 \fB\-mode\fR \fIbaud\fB,\fIparity\fB,\fIdata\fB,\fIstop\fR
440 This option is a set of 4 comma-separated values: the baud rate, parity,
441 number of data bits, and number of stop bits for this serial port. The
442 \fIbaud\fR rate is a simple integer that specifies the connection speed.
443 \fIParity\fR is one of the following letters: \fBn\fR, \fBo\fR, \fBe\fR,
444 \fBm\fR, \fBs\fR; respectively signifying the parity options of
451 \fIData\fR is the number of
452 data bits and should be an integer from 5 to 8, while \fIstop\fR is the
453 number of stop bits and should be the integer 1 or 2.
455 \fB\-handshake\fR \fItype\fR
457 (Windows and Unix). This option is used to setup automatic handshake
458 control. Note that not all handshake types maybe supported by your operating
459 system. The \fItype\fR parameter is case-independent.
462 If \fItype\fR is \fBnone\fR then any handshake is switched off.
463 \fBrtscts\fR activates hardware handshake. Hardware handshake signals
465 For software handshake \fBxonxoff\fR the handshake characters can be redefined
467 An additional hardware handshake \fBdtrdsr\fR is available only under Windows.
468 There is no default handshake configuration, the initial value depends
469 on your operating system settings.
470 The \fB\-handshake\fR option cannot be queried.
475 (Windows and Unix). The \fB\-queue\fR option can only be queried.
476 It returns a list of two integers representing the current number
477 of bytes in the input and output queue respectively.
479 \fB\-timeout\fR \fImsec\fR
481 (Windows and Unix). This option is used to set the timeout for blocking
482 read operations. It specifies the maximum interval between the
483 reception of two bytes in milliseconds.
484 For Unix systems the granularity is 100 milliseconds.
485 The \fB\-timeout\fR option does not affect write operations or
487 This option cannot be queried.
489 \fB\-ttycontrol\fR \fI{signal boolean signal boolean ...}\fR
491 (Windows and Unix). This option is used to setup the handshake
492 output lines (see below) permanently or to send a BREAK over the serial line.
493 The \fIsignal\fR names are case-independent.
494 \fB{RTS 1 DTR 0}\fR sets the RTS output to high and the DTR output to low.
495 The BREAK condition (see below) is enabled and disabled with \fB{BREAK 1}\fR and
496 \fB{BREAK 0}\fR respectively.
497 It is not a good idea to change the \fBRTS\fR (or \fBDTR\fR) signal
498 with active hardware handshake \fBrtscts\fR (or \fBdtrdsr\fR).
499 The result is unpredictable.
500 The \fB\-ttycontrol\fR option cannot be queried.
504 (Windows and Unix). The \fB\-ttystatus\fR option can only be
505 queried. It returns the current modem status and handshake input signals
507 The result is a list of signal,value pairs with a fixed order,
508 e.g. \fB{CTS 1 DSR 0 RING 1 DCD 0}\fR.
509 The \fIsignal\fR names are returned upper case.
511 \fB\-xchar\fR \fI{xonChar xoffChar}\fR
513 (Windows and Unix). This option is used to query or change the software
514 handshake characters. Normally the operating system default should be
515 DC1 (0x11) and DC3 (0x13) representing the ASCII standard
516 XON and XOFF characters.
518 \fB\-pollinterval\fR \fImsec\fR
520 (Windows only). This option is used to set the maximum time between
521 polling for fileevents.
522 This affects the time interval between checking for events throughout the Tcl
523 interpreter (the smallest value always wins). Use this option only if
524 you want to poll the serial port more or less often than 10 msec
527 \fB\-sysbuffer\fR \fIinSize\fR
529 \fB\-sysbuffer\fR \fI{inSize outSize}\fR
531 (Windows only). This option is used to change the size of Windows
532 system buffers for a serial channel. Especially at higher communication
533 rates the default input buffer size of 4096 bytes can overrun
534 for latent systems. The first form specifies the input buffer size,
535 in the second form both input and output buffers are defined.
539 (Windows only). This option is query only.
540 In case of a serial communication error, \fBread\fR or \fBputs\fR
541 returns a general Tcl file I/O error.
542 \fBfconfigure\fR \fB\-lasterror\fR can be called to get a list of error details.
543 See below for an explanation of the various error codes.
544 .SH "SERIAL PORT SIGNALS"
546 RS-232 is the most commonly used standard electrical interface for serial
547 communications. A negative voltage (-3V..-12V) define a mark (on=1) bit and
548 a positive voltage (+3..+12V) define a space (off=0) bit (RS-232C). The
549 following signals are specified for incoming and outgoing data, status
550 lines and handshaking. Here we are using the terms \fIworkstation\fR for
551 your computer and \fImodem\fR for the external device, because some signal
552 names (DCD, RI) come from modems. Of course your external device may use
553 these signal lines for other purposes.
554 .IP \fBTXD\fR(output)
555 \fBTransmitted Data:\fR Outgoing serial data.
557 \fBReceived Data:\fRIncoming serial data.
558 .IP \fBRTS\fR(output)
559 \fBRequest To Send:\fR This hardware handshake line informs the modem that
560 your workstation is ready to receive data. Your workstation may
561 automatically reset this signal to indicate that the input buffer is full.
563 \fBClear To Send:\fR The complement to RTS. Indicates that the modem is
564 ready to receive data.
565 .IP \fBDTR\fR(output)
566 \fBData Terminal Ready:\fR This signal tells the modem that the workstation
567 is ready to establish a link. DTR is often enabled automatically whenever a
568 serial port is opened.
570 \fBData Set Ready:\fR The complement to DTR. Tells the workstation that the
571 modem is ready to establish a link.
573 \fBData Carrier Detect:\fR This line becomes active when a modem detects a
577 \fBRing Indicator:\fR Goes active when the modem detects an incoming call.
579 A BREAK condition is not a hardware signal line, but a logical zero on the
580 TXD or RXD lines for a long period of time, usually 250 to 500
581 milliseconds. Normally a receive or transmit data signal stays at the mark
582 (on=1) voltage until the next character is transferred. A BREAK is sometimes
583 used to reset the communications line or change the operating mode of
584 communications hardware.
585 .SH "ERROR CODES (Windows only)"
587 A lot of different errors may occur during serial read operations or during
588 event polling in background. The external device may have been switched
589 off, the data lines may be noisy, system buffers may overrun or your mode
590 settings may be wrong. That is why a reliable software should always
591 \fBcatch\fR serial read operations. In cases of an error Tcl returns a
592 general file I/O error. Then \fBfconfigure\fR \fB\-lasterror\fR may help to
593 locate the problem. The following error codes may be returned.
597 Windows input buffer overrun. The data comes faster than your scripts reads
598 it or your system is overloaded. Use \fBfconfigure\fR \fB\-sysbuffer\fR to avoid a
599 temporary bottleneck and/or make your script faster.
603 Windows output buffer overrun. Complement to RXOVER. This error should
604 practically not happen, because Tcl cares about the output buffer status.
608 UART buffer overrun (hardware) with data lost.
609 The data comes faster than the system driver receives it.
610 Check your advanced serial port settings to enable the FIFO (16550) buffer
611 and/or setup a lower(1) interrupt threshold value.
615 A parity error has been detected by your UART.
616 Wrong parity settings with \fBfconfigure\fR \fB\-mode\fR or a noisy data line (RXD)
617 may cause this error.
621 A stop-bit error has been detected by your UART.
622 Wrong mode settings with \fBfconfigure\fR \fB\-mode\fR or a noisy data line (RXD)
623 may cause this error.
627 A BREAK condition has been detected by your UART (see above).
628 .SH "PORTABILITY ISSUES"
632 Valid values for \fIfileName\fR to open a serial port are of the form
633 \fBcom\fIX\fB\fR, where \fIX\fR is a number, generally from 1 to 9.
634 A legacy form accepted as well is \fBcom\fIX\fB:\fR. This notation only
635 works for serial ports from 1 to 9. An attempt to open a serial port that
636 does not exist or has a number greater than 9 will fail. An alternate
637 form of opening serial ports is to use the filename \fB//./comX\fR,
638 where X is any number that corresponds to a serial port.
641 When running Tcl interactively, there may be some strange interactions
642 between the real console, if one is present, and a command pipeline that uses
643 standard input or output. If a command pipeline is opened for reading, some
644 of the lines entered at the console will be sent to the command pipeline and
645 some will be sent to the Tcl evaluator. If a command pipeline is opened for
646 writing, keystrokes entered into the console are not visible until the
647 pipe is closed. These problems only occur because both Tcl and the child
648 application are competing for the console at the same time. If the command
649 pipeline is started from a script, so that Tcl is not accessing the console,
650 or if the command pipeline does not use standard input or output, but is
651 redirected from or to a file, then the above problems do not occur.
654 \fBUnix\fR\0\0\0\0\0\0\0
656 Valid values for \fIfileName\fR to open a serial port are generally of the
657 form \fB/dev/tty\fIX\fR, where \fIX\fR is \fBa\fR or \fBb\fR, but the name
658 of any pseudo-file that maps to a serial port may be used.
659 Advanced configuration options are only supported for serial ports
660 when Tcl is built to use the POSIX serial interface.
663 When running Tcl interactively, there may be some strange interactions
664 between the console, if one is present, and a command pipeline that uses
665 standard input. If a command pipeline is opened for reading, some
666 of the lines entered at the console will be sent to the command pipeline and
667 some will be sent to the Tcl evaluator. This problem only occurs because
668 both Tcl and the child application are competing for the console at the
669 same time. If the command pipeline is started from a script, so that Tcl is
670 not accessing the console, or if the command pipeline does not use standard
671 input, but is redirected from a file, then the above problem does not occur.
674 See the \fBPORTABILITY ISSUES\fR section of the \fBexec\fR command for
675 additional information not specific to command pipelines about executing
676 applications on the various platforms
679 Open a command pipeline and catch any errors:
682 set fl [\fBopen\fR "| ls this_file_does_not_exist"]
684 if {[catch {close $fl} err]} {
685 puts "ls command failed: $err"
689 file(n), close(n), filename(n), fconfigure(n), gets(n), read(n),
690 puts(n), exec(n), pid(n), fopen(3)
692 access mode, append, create, file, non-blocking, open, permissions,
693 pipeline, process, serial
OSDN Git Service
