| '\" |
| '\" Copyright (c) 1993 The Regents of the University of California. |
| '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. |
| '\" |
| '\" See the file "license.terms" for information on usage and redistribution |
| '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. |
| '\" |
| '\" RCS: @(#) $Id: open.n,v 1.16 2002/07/23 18:17:12 jenglish Exp $ |
| '\" |
| '\" The definitions below are for supplemental macros used in Tcl/Tk |
| '\" manual entries. |
| '\" |
| '\" .AP type name in/out ?indent? |
| '\" Start paragraph describing an argument to a library procedure. |
| '\" type is type of argument (int, etc.), in/out is either "in", "out", |
| '\" or "in/out" to describe whether procedure reads or modifies arg, |
| '\" and indent is equivalent to second arg of .IP (shouldn't ever be |
| '\" needed; use .AS below instead) |
| '\" |
| '\" .AS ?type? ?name? |
| '\" Give maximum sizes of arguments for setting tab stops. Type and |
| '\" name are examples of largest possible arguments that will be passed |
| '\" to .AP later. If args are omitted, default tab stops are used. |
| '\" |
| '\" .BS |
| '\" Start box enclosure. From here until next .BE, everything will be |
| '\" enclosed in one large box. |
| '\" |
| '\" .BE |
| '\" End of box enclosure. |
| '\" |
| '\" .CS |
| '\" Begin code excerpt. |
| '\" |
| '\" .CE |
| '\" End code excerpt. |
| '\" |
| '\" .VS ?version? ?br? |
| '\" Begin vertical sidebar, for use in marking newly-changed parts |
| '\" of man pages. The first argument is ignored and used for recording |
| '\" the version when the .VS was added, so that the sidebars can be |
| '\" found and removed when they reach a certain age. If another argument |
| '\" is present, then a line break is forced before starting the sidebar. |
| '\" |
| '\" .VE |
| '\" End of vertical sidebar. |
| '\" |
| '\" .DS |
| '\" Begin an indented unfilled display. |
| '\" |
| '\" .DE |
| '\" End of indented unfilled display. |
| '\" |
| '\" .SO |
| '\" Start of list of standard options for a Tk widget. The |
| '\" options follow on successive lines, in four columns separated |
| '\" by tabs. |
| '\" |
| '\" .SE |
| '\" End of list of standard options for a Tk widget. |
| '\" |
| '\" .OP cmdName dbName dbClass |
| '\" Start of description of a specific option. cmdName gives the |
| '\" option's name as specified in the class command, dbName gives |
| '\" the option's name in the option database, and dbClass gives |
| '\" the option's class in the option database. |
| '\" |
| '\" .UL arg1 arg2 |
| '\" Print arg1 underlined, then print arg2 normally. |
| '\" |
| '\" RCS: @(#) $Id: man.macros,v 1.4 2000/08/25 06:18:32 ericm Exp $ |
| '\" |
| '\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. |
| .if t .wh -1.3i ^B |
| .nr ^l \n(.l |
| .ad b |
| '\" # Start an argument description |
| .de AP |
| .ie !"\\$4"" .TP \\$4 |
| .el \{\ |
| . ie !"\\$2"" .TP \\n()Cu |
| . el .TP 15 |
| .\} |
| .ta \\n()Au \\n()Bu |
| .ie !"\\$3"" \{\ |
| \&\\$1 \\fI\\$2\\fP (\\$3) |
| .\".b |
| .\} |
| .el \{\ |
| .br |
| .ie !"\\$2"" \{\ |
| \&\\$1 \\fI\\$2\\fP |
| .\} |
| .el \{\ |
| \&\\fI\\$1\\fP |
| .\} |
| .\} |
| .. |
| '\" # define tabbing values for .AP |
| .de AS |
| .nr )A 10n |
| .if !"\\$1"" .nr )A \\w'\\$1'u+3n |
| .nr )B \\n()Au+15n |
| .\" |
| .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n |
| .nr )C \\n()Bu+\\w'(in/out)'u+2n |
| .. |
| .AS Tcl_Interp Tcl_CreateInterp in/out |
| '\" # BS - start boxed text |
| '\" # ^y = starting y location |
| '\" # ^b = 1 |
| .de BS |
| .br |
| .mk ^y |
| .nr ^b 1u |
| .if n .nf |
| .if n .ti 0 |
| .if n \l'\\n(.lu\(ul' |
| .if n .fi |
| .. |
| '\" # BE - end boxed text (draw box now) |
| .de BE |
| .nf |
| .ti 0 |
| .mk ^t |
| .ie n \l'\\n(^lu\(ul' |
| .el \{\ |
| .\" Draw four-sided box normally, but don't draw top of |
| .\" box if the box started on an earlier page. |
| .ie !\\n(^b-1 \{\ |
| \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' |
| .\} |
| .el \}\ |
| \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' |
| .\} |
| .\} |
| .fi |
| .br |
| .nr ^b 0 |
| .. |
| '\" # VS - start vertical sidebar |
| '\" # ^Y = starting y location |
| '\" # ^v = 1 (for troff; for nroff this doesn't matter) |
| .de VS |
| .if !"\\$2"" .br |
| .mk ^Y |
| .ie n 'mc \s12\(br\s0 |
| .el .nr ^v 1u |
| .. |
| '\" # VE - end of vertical sidebar |
| .de VE |
| .ie n 'mc |
| .el \{\ |
| .ev 2 |
| .nf |
| .ti 0 |
| .mk ^t |
| \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' |
| .sp -1 |
| .fi |
| .ev |
| .\} |
| .nr ^v 0 |
| .. |
| '\" # Special macro to handle page bottom: finish off current |
| '\" # box/sidebar if in box/sidebar mode, then invoked standard |
| '\" # page bottom macro. |
| .de ^B |
| .ev 2 |
| 'ti 0 |
| 'nf |
| .mk ^t |
| .if \\n(^b \{\ |
| .\" Draw three-sided box if this is the box's first page, |
| .\" draw two sides but no top otherwise. |
| .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 |
| .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c |
| .\} |
| .if \\n(^v \{\ |
| .nr ^x \\n(^tu+1v-\\n(^Yu |
| \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c |
| .\} |
| .bp |
| 'fi |
| .ev |
| .if \\n(^b \{\ |
| .mk ^y |
| .nr ^b 2 |
| .\} |
| .if \\n(^v \{\ |
| .mk ^Y |
| .\} |
| .. |
| '\" # DS - begin display |
| .de DS |
| .RS |
| .nf |
| .sp |
| .. |
| '\" # DE - end display |
| .de DE |
| .fi |
| .RE |
| .sp |
| .. |
| '\" # SO - start of list of standard options |
| .de SO |
| .SH "STANDARD OPTIONS" |
| .LP |
| .nf |
| .ta 5.5c 11c |
| .ft B |
| .. |
| '\" # SE - end of list of standard options |
| .de SE |
| .fi |
| .ft R |
| .LP |
| See the \\fBoptions\\fR manual entry for details on the standard options. |
| .. |
| '\" # OP - start of full description for a single option |
| .de OP |
| .LP |
| .nf |
| .ta 4c |
| Command-Line Name: \\fB\\$1\\fR |
| Database Name: \\fB\\$2\\fR |
| Database Class: \\fB\\$3\\fR |
| .fi |
| .IP |
| .. |
| '\" # CS - begin code excerpt |
| .de CS |
| .RS |
| .nf |
| .ta .25i .5i .75i 1i |
| .. |
| '\" # CE - end code excerpt |
| .de CE |
| .fi |
| .RE |
| .. |
| .de UL |
| \\$1\l'|0\(ul'\\$2 |
| .. |
| .TH open n 8.3 Tcl "Tcl Built-In Commands" |
| .BS |
| '\" Note: do not modify the .SH NAME line immediately below! |
| .SH NAME |
| open \- Open a file-based or command pipeline channel |
| .SH SYNOPSIS |
| .sp |
| \fBopen \fIfileName\fR |
| .br |
| \fBopen \fIfileName access\fR |
| .br |
| \fBopen \fIfileName access permissions\fR |
| .BE |
| |
| .SH DESCRIPTION |
| .PP |
| This command opens a file, serial port, or command pipeline and returns a |
| channel identifier that may be used in future invocations of commands like |
| \fBread\fR, \fBputs\fR, and \fBclose\fR. |
| If the first character of \fIfileName\fR is not \fB|\fR then |
| the command opens a file: |
| \fIfileName\fR gives the name of the file to open, and it must conform to the |
| conventions described in the \fBfilename\fR manual entry. |
| .PP |
| The \fIaccess\fR argument, if present, indicates the way in which the file |
| (or command pipeline) is to be accessed. |
| In the first form \fIaccess\fR may have any of the following values: |
| .TP 15 |
| \fBr\fR |
| Open the file for reading only; the file must already exist. This is the |
| default value if \fIaccess\fR is not specified. |
| .TP 15 |
| \fBr+\fR |
| Open the file for both reading and writing; the file must |
| already exist. |
| .TP 15 |
| \fBw\fR |
| Open the file for writing only. Truncate it if it exists. If it doesn't |
| exist, create a new file. |
| .TP 15 |
| \fBw+\fR |
| Open the file for reading and writing. Truncate it if it exists. |
| If it doesn't exist, create a new file. |
| .TP 15 |
| \fBa\fR |
| Open the file for writing only. If the file doesn't exist, |
| create a new empty file. |
| Set the initial access position to the end of the file. |
| .TP 15 |
| \fBa+\fR |
| Open the file for reading and writing. If the file doesn't exist, |
| create a new empty file. |
| Set the initial access position to the end of the file. |
| .PP |
| In the second form, \fIaccess\fR consists of a list of any of the |
| following flags, all of which have the standard POSIX meanings. |
| One of the flags must be either \fBRDONLY\fR, \fBWRONLY\fR or \fBRDWR\fR. |
| .TP 15 |
| \fBRDONLY\fR |
| Open the file for reading only. |
| .TP 15 |
| \fBWRONLY\fR |
| Open the file for writing only. |
| .TP 15 |
| \fBRDWR\fR |
| Open the file for both reading and writing. |
| .TP 15 |
| \fBAPPEND\fR |
| Set the file pointer to the end of the file prior to each write. |
| .TP 15 |
| \fBCREAT\fR |
| Create the file if it doesn't already exist (without this flag it |
| is an error for the file not to exist). |
| .TP 15 |
| \fBEXCL\fR |
| If \fBCREAT\fR is also specified, an error is returned if the |
| file already exists. |
| .TP 15 |
| \fBNOCTTY\fR |
| If the file is a terminal device, this flag prevents the file from |
| becoming the controlling terminal of the process. |
| .TP 15 |
| \fBNONBLOCK\fR |
| Prevents the process from blocking while opening the file, and |
| possibly in subsequent I/O operations. The exact behavior of |
| this flag is system- and device-dependent; its use is discouraged |
| (it is better to use the \fBfconfigure\fR command to put a file |
| in nonblocking mode). |
| For details refer to your system documentation on the \fBopen\fR system |
| call's \fBO_NONBLOCK\fR flag. |
| .TP 15 |
| \fBTRUNC\fR |
| If the file exists it is truncated to zero length. |
| .PP |
| If a new file is created as part of opening it, \fIpermissions\fR |
| (an integer) is used to set the permissions for the new file in |
| conjunction with the process's file mode creation mask. |
| \fIPermissions\fR defaults to 0666. |
| .PP |
| Note that if you are going to be reading or writing binary data from |
| the channel created by this command, you should use the |
| \fBfconfigure\fR command to change the \fB-translation\fR option of |
| the channel to \fBbinary\fR before transferring any binary data. This |
| is in contrast to the ``b'' character passed as part of the equivalent |
| of the \fIaccess\fR parameter to some versions of the C library |
| \fIfopen()\fR function. |
| |
| .SH "COMMAND PIPELINES" |
| .PP |
| If the first character of \fIfileName\fR is ``|'' then the |
| remaining characters of \fIfileName\fR are treated as a list of arguments |
| that describe a command pipeline to invoke, in the same style as the |
| arguments for \fBexec\fR. |
| In this case, the channel identifier returned by \fBopen\fR may be used |
| to write to the command's input pipe or read from its output pipe, |
| depending on the value of \fIaccess\fR. |
| If write-only access is used (e.g. \fIaccess\fR is \fBw\fR), then |
| standard output for the pipeline is directed to the current standard |
| output unless overridden by the command. |
| If read-only access is used (e.g. \fIaccess\fR is \fBr\fR), |
| standard input for the pipeline is taken from the current standard |
| input unless overridden by the command. |
| The id of the spawned process is accessible through the \fBpid\fR |
| command, using the channel id returned by \fBopen\fR as argument. |
| |
| .VS 8.4 |
| .SH "SERIAL COMMUNICATIONS" |
| .PP |
| If \fIfileName\fR refers to a serial port, then the specified serial port |
| is opened and initialized in a platform-dependent manner. Acceptable |
| values for the \fIfileName\fR to use to open a serial port are described in |
| the PORTABILITY ISSUES section. |
| .PP |
| The \fBfconfigure\fR command can be used to query and set additional |
| configuration options specific to serial ports. |
| .VE |
| |
| .SH "PORTABILITY ISSUES" |
| .TP |
| \fBWindows \fR(all versions) |
| . |
| Valid values for \fIfileName\fR to open a serial port are of the form |
| \fBcom\fIX\fB:\fR, where \fIX\fR is a number, generally from 1 to 4. |
| This notation only works for serial ports from 1 to 9, if the system |
| happens to have more than four. An attempt to open a serial port that |
| does not exist or has a number greater than 9 will fail. An alternate |
| form of opening serial ports is to use the filename \fB\e\e.\ecomX\fR, |
| where X is any number that corresponds to a serial port; please note |
| that this method is considerably slower on Windows 95 and Windows 98. |
| .TP |
| \fBWindows NT\fR |
| . |
| When running Tcl interactively, there may be some strange interactions |
| between the real console, if one is present, and a command pipeline that uses |
| standard input or output. If a command pipeline is opened for reading, some |
| of the lines entered at the console will be sent to the command pipeline and |
| some will be sent to the Tcl evaluator. If a command pipeline is opened for |
| writing, keystrokes entered into the console are not visible until the the |
| pipe is closed. This behavior occurs whether the command pipeline is |
| executing 16-bit or 32-bit applications. These problems only occur because |
| both Tcl and the child application are competing for the console at |
| the same time. If the command pipeline is started from a script, so that Tcl |
| is not accessing the console, or if the command pipeline does not use |
| standard input or output, but is redirected from or to a file, then the |
| above problems do not occur. |
| .TP |
| \fBWindows 95\fR |
| . |
| A command pipeline that executes a 16-bit DOS application cannot be opened |
| for both reading and writing, since 16-bit DOS applications that receive |
| standard input from a pipe and send standard output to a pipe run |
| synchronously. Command pipelines that do not execute 16-bit DOS |
| applications run asynchronously and can be opened for both reading and |
| writing. |
| .sp |
| When running Tcl interactively, there may be some strange interactions |
| between the real console, if one is present, and a command pipeline that uses |
| standard input or output. If a command pipeline is opened for reading from |
| a 32-bit application, some of the keystrokes entered at the console will be |
| sent to the command pipeline and some will be sent to the Tcl evaluator. If |
| a command pipeline is opened for writing to a 32-bit application, no output |
| is visible on the console until the the pipe is closed. These problems only |
| occur because both Tcl and the child application are competing for the |
| console at the same time. If the command pipeline is started from a script, |
| so that Tcl is not accessing the console, or if the command pipeline does |
| not use standard input or output, but is redirected from or to a file, then |
| the above problems do not occur. |
| .sp |
| Whether or not Tcl is running interactively, if a command pipeline is opened |
| for reading from a 16-bit DOS application, the call to \fBopen\fR will not |
| return until end-of-file has been received from the command pipeline's |
| standard output. If a command pipeline is opened for writing to a 16-bit DOS |
| application, no data will be sent to the command pipeline's standard output |
| until the pipe is actually closed. This problem occurs because 16-bit DOS |
| applications are run synchronously, as described above. |
| .TP |
| \fBMacintosh\fR |
| . |
| Opening a serial port is not currently implemented under Macintosh. |
| .sp |
| Opening a command pipeline is not supported under Macintosh, since |
| applications do not support the concept of standard input or output. |
| .TP |
| \fBUnix\fR\0\0\0\0\0\0\0 |
| . |
| Valid values for \fIfileName\fR to open a serial port are generally of the |
| form \fB/dev/tty\fIX\fR, where \fIX\fR is \fBa\fR or \fBb\fR, but the name |
| of any pseudo-file that maps to a serial port may be used. |
| .sp |
| When running Tcl interactively, there may be some strange interactions |
| between the console, if one is present, and a command pipeline that uses |
| standard input. If a command pipeline is opened for reading, some |
| of the lines entered at the console will be sent to the command pipeline and |
| some will be sent to the Tcl evaluator. This problem only occurs because |
| both Tcl and the child application are competing for the console at the |
| same time. If the command pipeline is started from a script, so that Tcl is |
| not accessing the console, or if the command pipeline does not use standard |
| input, but is redirected from a file, then the above problem does not occur. |
| .LP |
| See the PORTABILITY ISSUES section of the \fBexec\fR command for additional |
| information not specific to command pipelines about executing |
| applications on the various platforms |
| |
| .SH "SEE ALSO" |
| file(n), close(n), filename(n), fconfigure(n), gets(n), read(n), |
| puts(n), exec(n), pid(n), fopen(3) |
| |
| .SH KEYWORDS |
| access mode, append, create, file, non-blocking, open, permissions, |
| pipeline, process, serial |