open(n) Tcl Built-In Commands open(n) _________________________________________________________________ NAME open - Open a file-based or command pipeline channel SYNOPSIS open _f_i_l_e_N_a_m_e open _f_i_l_e_N_a_m_e _a_c_c_e_s_s open _f_i_l_e_N_a_m_e _a_c_c_e_s_s _p_e_r_m_i_s_s_i_o_n_s _________________________________________________________________ DESCRIPTION This command opens a file or command pipeline and returns a channel identifier that may be used in future invocations of commands like read, puts, and close. If the first character of _f_i_l_e_N_a_m_e is not | then the command opens a file: _f_i_l_e_N_a_m_e gives the name of the file to open, and it must conform to the conventions described in the filename manual entry. The _a_c_c_e_s_s argument, if present, indicates the way in which the file (or command pipeline) is to be accessed. In the first form _a_c_c_e_s_s may have any of the following values: r Open the file for reading only; the file must already exist. This is the default value if _a_c_c_e_s_s is not specified. r+ Open the file for both reading and writing; the file must already exist. w Open the file for writing only. Truncate it if it exists. If it doesn't exist, create a new file. w+ Open the file for reading and writing. Trun- cate it if it exists. If it doesn't exist, create a new file. a Open the file for writing only. The file must already exist, and the file is posi- tioned so that new data is appended to the file. a+ 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. In the second form, _a_c_c_e_s_s consists of a list of any of the following flags, all of which have the standard POSIX Tcl Last change: 7.6 1 open(n) Tcl Built-In Commands open(n) meanings. One of the flags must be either RDONLY, WRONLY or RDWR. RDONLY Open the file for reading only. WRONLY Open the file for writing only. RDWR Open the file for both reading and writing. APPEND Set the file pointer to the end of the file prior to each write. CREAT Create the file if it doesn't already exist (without this flag it is an error for the file not to exist). EXCL If CREAT is also specified, an error is returned if the file already exists. NOCTTY If the file is a terminal device, this flag prevents the file from becoming the control- ling terminal of the process. NONBLOCK 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 fconfigure command to put a file in nonblock- ing mode). For details refer to your system documentation on the open system call's O_NONBLOCK flag. TRUNC If the file exists it is truncated to zero length. If a new file is created as part of opening it, _p_e_r_m_i_s_s_i_o_n_s (an integer) is used to set the permissions for the new file in conjunction with the process's file mode creation mask. _P_e_r_m_i_s_s_i_o_n_s defaults to 0666. COMMAND PIPELINES If the first character of _f_i_l_e_N_a_m_e is ``|'' then the remain- ing characters of _f_i_l_e_N_a_m_e are treated as a list of argu- ments that describe a command pipeline to invoke, in the same style as the arguments for exec. In this case, the channel identifier returned by open may be used to write to the command's input pipe or read from its output pipe, depending on the value of _a_c_c_e_s_s. If write-only access is used (e.g. _a_c_c_e_s_s is w), then standard output for the pipe- line is directed to the current standard output unless over- ridden by the command. If read-only access is used (e.g. Tcl Last change: 7.6 2 open(n) Tcl Built-In Commands open(n) _a_c_c_e_s_s is r), standard input for the pipeline is taken from the current standard input unless overridden by the command. PORTABILITY ISSUES | Windows NT | | | 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 execut- | ing 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 pipe- | line does not use standard input or output, but is | redirected from or to a file, then the above problems | do not occur. | Win- | dows 95 | | | A command pipeline that executes a 16-bit DOS applica- | tion 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 exe- | cute 16-bit DOS applications run asynchronously and can | be opened for both reading and writing. | 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 keys- | trokes entered at the console will be sent to the com- | mand pipeline and some will be sent to the Tcl evalua- | tor. 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 pipe- | line does not use standard input or output, but is | Tcl Last change: 7.6 3 open(n) Tcl Built-In Commands open(n) redirected from or to a file, then the above problems | do not occur. | Whether or not Tcl is running interactively, if a com- | mand pipeline is opened for reading from a 16-bit DOS | application, the call to open 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. | Windows 3.X | | | A command pipeline can execute 16-bit or 32-bit DOS or | Windows applications, but the call to open will not | return until the last program in the pipeline has fin- | ished executing; command pipelines run synchronously. | If the pipeline is opened with write access (either | just writing or both reading and writing) the first | application in the pipeline will instead see an immedi- | ate end-of-file; any data the caller writes to the open | pipe will instead be discarded. | Since Tcl cannot be run with a real console under Win- | dows 3.X, there are no interactions between command | pipelines and the console. | Macin- | tosh | | | Opening a command pipeline is not supported under | Macintosh, since applications do not support the con- | cept of standard input or output. | Unix | | | 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 stan- | dard input, but is redirected from a file, then the | above problem does not occur. | Tcl Last change: 7.6 4 open(n) Tcl Built-In Commands open(n) See the PORTABILITY ISSUES section of the exec command for | additional information not specific to command pipelines | about executing applications on the various platforms | SEE ALSO | close(n), filename(n), gets(n), read(n), puts(n), exec(n) KEYWORDS access mode, append, create, file, non-blocking, open, per- missions, pipeline, process Tcl Last change: 7.6 5