1 |
578 |
markom |
'\"
|
2 |
|
|
'\" Copyright (c) 1996-1997 Sun Microsystems, Inc.
|
3 |
|
|
'\"
|
4 |
|
|
'\" See the file "license.terms" for information on usage and redistribution
|
5 |
|
|
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
6 |
|
|
'\"
|
7 |
|
|
'\" RCS: @(#) $Id: OpenFileChnl.3,v 1.1.1.1 2002-01-16 10:25:24 markom Exp $
|
8 |
|
|
.so man.macros
|
9 |
|
|
.TH Tcl_OpenFileChannel 3 8.0 Tcl "Tcl Library Procedures"
|
10 |
|
|
.BS
|
11 |
|
|
'\" Note: do not modify the .SH NAME line immediately below!
|
12 |
|
|
.SH NAME
|
13 |
|
|
Tcl_OpenFileChannel, Tcl_OpenCommandChannel, Tcl_MakeFileChannel, Tcl_GetChannel, Tcl_RegisterChannel, Tcl_UnregisterChannel, Tcl_Close, Tcl_Read, Tcl_Gets, Tcl_Write, Tcl_Flush, Tcl_Seek, Tcl_Tell, Tcl_Eof, Tcl_InputBlocked, Tcl_InputBuffered, Tcl_GetChannelOption, Tcl_SetChannelOption \- buffered I/O facilities using channels
|
14 |
|
|
.SH SYNOPSIS
|
15 |
|
|
.nf
|
16 |
|
|
\fB#include \fR
|
17 |
|
|
.sp
|
18 |
|
|
typedef ... Tcl_Channel;
|
19 |
|
|
.sp
|
20 |
|
|
Tcl_Channel
|
21 |
|
|
\fBTcl_OpenFileChannel\fR(\fIinterp, fileName, mode, permissions\fR)
|
22 |
|
|
.sp
|
23 |
|
|
Tcl_Channel
|
24 |
|
|
\fBTcl_OpenCommandChannel\fR(\fIinterp, argc, argv, flags\fR)
|
25 |
|
|
.VS
|
26 |
|
|
.sp
|
27 |
|
|
Tcl_Channel
|
28 |
|
|
\fBTcl_MakeFileChannel\fR(\fIhandle, readOrWrite\fR)
|
29 |
|
|
.VE
|
30 |
|
|
.sp
|
31 |
|
|
Tcl_Channel
|
32 |
|
|
\fBTcl_GetChannel\fR(\fIinterp, channelName, modePtr\fR)
|
33 |
|
|
.sp
|
34 |
|
|
void
|
35 |
|
|
\fBTcl_RegisterChannel\fR(\fIinterp, channel\fR)
|
36 |
|
|
.sp
|
37 |
|
|
int
|
38 |
|
|
\fBTcl_UnregisterChannel\fR(\fIinterp, channel\fR)
|
39 |
|
|
.sp
|
40 |
|
|
int
|
41 |
|
|
\fBTcl_Close\fR(\fIinterp, channel\fR)
|
42 |
|
|
.sp
|
43 |
|
|
int
|
44 |
|
|
\fBTcl_Read\fR(\fIchannel, buf, toRead\fR)
|
45 |
|
|
.sp
|
46 |
|
|
int
|
47 |
|
|
\fBTcl_Gets\fR(\fIchannel, lineRead\fR)
|
48 |
|
|
.sp
|
49 |
|
|
int
|
50 |
|
|
\fBTcl_GetsObj\fR(\fIchannel, lineObjPtr\fR)
|
51 |
|
|
.sp
|
52 |
|
|
int
|
53 |
|
|
\fBTcl_Write\fR(\fIchannel, buf, toWrite\fR)
|
54 |
|
|
.sp
|
55 |
|
|
int
|
56 |
|
|
\fBTcl_Flush\fR(\fIchannel\fR)
|
57 |
|
|
.sp
|
58 |
|
|
int
|
59 |
|
|
\fBTcl_Seek\fR(\fIchannel, offset, seekMode\fR)
|
60 |
|
|
.sp
|
61 |
|
|
int
|
62 |
|
|
\fBTcl_Tell\fR(\fIchannel\fR)
|
63 |
|
|
.sp
|
64 |
|
|
int
|
65 |
|
|
\fBTcl_GetChannelOption\fR(\fIinterp, channel, optionName, optionValue\fR)
|
66 |
|
|
.sp
|
67 |
|
|
int
|
68 |
|
|
\fBTcl_SetChannelOption\fR(\fIinterp, channel, optionName, newValue\fR)
|
69 |
|
|
.sp
|
70 |
|
|
int
|
71 |
|
|
\fBTcl_Eof\fR(\fIchannel\fR)
|
72 |
|
|
.sp
|
73 |
|
|
int
|
74 |
|
|
\fBTcl_InputBlocked\fR(\fIchannel\fR)
|
75 |
|
|
.sp
|
76 |
|
|
int
|
77 |
|
|
\fBTcl_InputBuffered\fR(\fIchannel\fR)
|
78 |
|
|
.sp
|
79 |
|
|
.SH ARGUMENTS
|
80 |
|
|
.AS Tcl_ChannelType newClientProcPtr in
|
81 |
|
|
.AP Tcl_Interp *interp in
|
82 |
|
|
Used for error reporting and to look up a channel registered in it.
|
83 |
|
|
.AP char *fileName in
|
84 |
|
|
The name of a local or network file.
|
85 |
|
|
.AP char *mode in
|
86 |
|
|
Specifies how the file is to be accessed. May have any of the
|
87 |
|
|
values allowed for the \fImode\fR argument to the Tcl
|
88 |
|
|
\fBopen\fR command.
|
89 |
|
|
For \fBTcl_OpenCommandChannel\fR, may be NULL.
|
90 |
|
|
.AP int permissions in
|
91 |
|
|
POSIX-style permission flags such as 0644.
|
92 |
|
|
If a new file is created, these permissions will be set on the
|
93 |
|
|
created file.
|
94 |
|
|
.AP int argc in
|
95 |
|
|
The number of elements in \fIargv\fR.
|
96 |
|
|
.AP char **argv in
|
97 |
|
|
Arguments for constructing a command pipeline.
|
98 |
|
|
These values have the same meaning as the non-switch arguments
|
99 |
|
|
to the Tcl \fBexec\fR command.
|
100 |
|
|
.AP int flags in
|
101 |
|
|
Specifies the disposition of the stdio handles in pipeline: OR-ed
|
102 |
|
|
combination of \fBTCL_STDIN\fR, \fBTCL_STDOUT\fR, \fBTCL_STDERR\fR,
|
103 |
|
|
and \fBTCL_ENFORCE_MODE\fR. If \fBTCL_STDIN\fR is set, stdin for
|
104 |
|
|
the first child in the pipe is the pipe channel, otherwise it is the same
|
105 |
|
|
as the standard input of the invoking process; likewise for
|
106 |
|
|
\fBTCL_STDOUT\fR and \fBTCL_STDERR\fR. If \fBTCL_ENFORCE_MODE\fR is not set,
|
107 |
|
|
then the pipe can redirect stdio handles to override the stdio handles for
|
108 |
|
|
which \fBTCL_STDIN\fR, \fBTCL_STDOUT\fR and \fBTCL_STDERR\fR have been set.
|
109 |
|
|
If it is set, then such redirections cause an error.
|
110 |
|
|
.VS
|
111 |
|
|
.AP ClientData handle in
|
112 |
|
|
Operating system specific handle for I/O to a file. For Unix this is a
|
113 |
|
|
file descriptor, for Windows it is a HANDLE.
|
114 |
|
|
.AP int readOrWrite in
|
115 |
|
|
OR-ed combination of \fBTCL_READABLE\fR and \fBTCL_WRITABLE\fR to indicate
|
116 |
|
|
what operations are valid on \fIhandle\fR.
|
117 |
|
|
.VE
|
118 |
|
|
.AP int *modePtr out
|
119 |
|
|
Points at an integer variable that will receive an OR-ed combination of
|
120 |
|
|
\fBTCL_READABLE\fR and \fBTCL_WRITABLE\fR denoting whether the channel is
|
121 |
|
|
open for reading and writing.
|
122 |
|
|
.AP Tcl_Channel channel in
|
123 |
|
|
A Tcl channel for input or output. Must have been the return value
|
124 |
|
|
from a procedure such as \fBTcl_OpenFileChannel\fR.
|
125 |
|
|
.AP char *buf in
|
126 |
|
|
An array of bytes in which to store channel input, or from which
|
127 |
|
|
to read channel output.
|
128 |
|
|
.AP int len in
|
129 |
|
|
The length of the input or output.
|
130 |
|
|
.AP int atEnd in
|
131 |
|
|
If nonzero, store the input at the end of the input queue, otherwise store
|
132 |
|
|
it at the head of the input queue.
|
133 |
|
|
.AP int toRead in
|
134 |
|
|
The number of bytes to read from the channel.
|
135 |
|
|
.AP Tcl_DString *lineRead in
|
136 |
|
|
A pointer to a Tcl dynamic string in which to store the line read from the
|
137 |
|
|
channel. Must have been initialized by the caller. The line read
|
138 |
|
|
will be appended to any data already in the dynamic string.
|
139 |
|
|
.AP Tcl_Obj *linePtrObj in
|
140 |
|
|
A pointer to a Tcl object in which to store the line read from the
|
141 |
|
|
channel. The line read will be appended to the current value of the
|
142 |
|
|
object.
|
143 |
|
|
.AP int toWrite in
|
144 |
|
|
The number of bytes to read from \fIbuf\fR and output to the channel.
|
145 |
|
|
.AP int offset in
|
146 |
|
|
How far to move the access point in the channel at which the next input or
|
147 |
|
|
output operation will be applied, measured in bytes from the position
|
148 |
|
|
given by \fIseekMode\fR. May be either positive or negative.
|
149 |
|
|
.AP int seekMode in
|
150 |
|
|
Relative to which point to seek; used with \fIoffset\fR to calculate the new
|
151 |
|
|
access point for the channel. Legal values are \fBSEEK_SET\fR,
|
152 |
|
|
\fBSEEK_CUR\fR, and \fBSEEK_END\fR.
|
153 |
|
|
.AP char *optionName in
|
154 |
|
|
The name of an option applicable to this channel, such as \fB\-blocking\fR.
|
155 |
|
|
May have any of the values accepted by the \fBfconfigure\fR command.
|
156 |
|
|
.AP Tcl_DString *optionValue in
|
157 |
|
|
Where to store the value of an option or a list of all options and their
|
158 |
|
|
values. Must have been initialized by the caller.
|
159 |
|
|
.AP char *newValue in
|
160 |
|
|
New value for the option given by \fIoptionName\fR.
|
161 |
|
|
.BE
|
162 |
|
|
|
163 |
|
|
.SH DESCRIPTION
|
164 |
|
|
.PP
|
165 |
|
|
The Tcl channel mechanism provides a device-independent and
|
166 |
|
|
platform-independent mechanism for performing buffered input
|
167 |
|
|
and output operations on a variety of file, socket, and device
|
168 |
|
|
types.
|
169 |
|
|
The channel mechanism is extensible to new channel types, by
|
170 |
|
|
providing a low level channel driver for the new type; the channel driver
|
171 |
|
|
interface is described in the manual entry for \fBTcl_CreateChannel\fR. The
|
172 |
|
|
channel mechanism provides a buffering scheme modelled after
|
173 |
|
|
Unix's standard I/O, and it also allows for nonblocking I/O on
|
174 |
|
|
channels.
|
175 |
|
|
.PP
|
176 |
|
|
The procedures described in this manual entry comprise the C APIs of the
|
177 |
|
|
generic layer of the channel architecture. For a description of the channel
|
178 |
|
|
driver architecture and how to implement channel drivers for new types of
|
179 |
|
|
channels, see the manual entry for \fBTcl_CreateChannel\fR.
|
180 |
|
|
|
181 |
|
|
.SH TCL_OPENFILECHANNEL
|
182 |
|
|
.PP
|
183 |
|
|
\fBTcl_OpenFileChannel\fR opens a file specified by \fIfileName\fR and
|
184 |
|
|
returns a channel handle that can be used to perform input and output on
|
185 |
|
|
the file. This API is modelled after the \fBfopen\fR procedure of
|
186 |
|
|
the Unix standard I/O library.
|
187 |
|
|
The syntax and meaning of all arguments is similar to those
|
188 |
|
|
given in the Tcl \fBopen\fR command when opening a file.
|
189 |
|
|
If an error occurs while opening the channel, \fBTcl_OpenFileChannel\fR
|
190 |
|
|
returns NULL and records a POSIX error code that can be
|
191 |
|
|
retrieved with \fBTcl_GetErrno\fR.
|
192 |
|
|
In addition, if \fIinterp\fR is non-NULL, \fBTcl_OpenFileChannel\fR
|
193 |
|
|
leaves an error message in \fIinterp->result\fR after any error.
|
194 |
|
|
.PP
|
195 |
|
|
The newly created channel is not registered in the supplied interpreter; to
|
196 |
|
|
register it, use \fBTcl_RegisterChannel\fR, described below.
|
197 |
|
|
If one of the standard channels, \fBstdin, stdout\fR or \fBstderr\fR was
|
198 |
|
|
previously closed, the act of creating the new channel also assigns it as a
|
199 |
|
|
replacement for the standard channel.
|
200 |
|
|
|
201 |
|
|
.SH TCL_OPENCOMMANDCHANNEL
|
202 |
|
|
.PP
|
203 |
|
|
\fBTcl_OpenCommandChannel\fR provides a C-level interface to the
|
204 |
|
|
functions of the \fBexec\fR and \fBopen\fR commands.
|
205 |
|
|
It creates a sequence of subprocesses specified
|
206 |
|
|
by the \fIargv\fR and \fIargc\fR arguments and returns a channel that can
|
207 |
|
|
be used to communicate with these subprocesses.
|
208 |
|
|
The \fIflags\fR argument indicates what sort of communication will
|
209 |
|
|
exist with the command pipeline.
|
210 |
|
|
.PP
|
211 |
|
|
If the \fBTCL_STDIN\fR flag is set then the standard input for the
|
212 |
|
|
first subprocess will be tied to the channel: writing to the channel
|
213 |
|
|
will provide input to the subprocess. If \fBTCL_STDIN\fR is not set,
|
214 |
|
|
then standard input for the first subprocess will be the same as this
|
215 |
|
|
application's standard input. If \fBTCL_STDOUT\fR is set then
|
216 |
|
|
standard output from the last subprocess can be read from the channel;
|
217 |
|
|
otherwise it goes to this application's standard output. If
|
218 |
|
|
\fBTCL_STDERR\fR is set, standard error output for all subprocesses is
|
219 |
|
|
returned to the channel and results in an error when the channel is
|
220 |
|
|
closed; otherwise it goes to this application's standard error. If
|
221 |
|
|
\fBTCL_ENFORCE_MODE\fR is not set, then \fIargc\fR and \fIargv\fR can
|
222 |
|
|
redirect the stdio handles to override \fBTCL_STDIN\fR,
|
223 |
|
|
\fBTCL_STDOUT\fR, and \fBTCL_STDERR\fR; if it is set, then it is an
|
224 |
|
|
error for argc and argv to override stdio channels for which
|
225 |
|
|
\fBTCL_STDIN\fR, \fBTCL_STDOUT\fR, and \fBTCL_STDERR\fR have been set.
|
226 |
|
|
.PP
|
227 |
|
|
If an error occurs while opening the channel, \fBTcl_OpenCommandChannel\fR
|
228 |
|
|
returns NULL and records a POSIX error code that can be retrieved with
|
229 |
|
|
\fBTcl_GetErrno\fR.
|
230 |
|
|
In addition, \fBTcl_OpenCommandChannel\fR leaves an error message in
|
231 |
|
|
\fIinterp->result\fR if \fIinterp\fR is not NULL.
|
232 |
|
|
.PP
|
233 |
|
|
The newly created channel is not registered in the supplied interpreter; to
|
234 |
|
|
register it, use \fBTcl_RegisterChannel\fR, described below.
|
235 |
|
|
If one of the standard channels, \fBstdin, stdout\fR or \fBstderr\fR was
|
236 |
|
|
previously closed, the act of creating the new channel also assigns it as a
|
237 |
|
|
replacement for the standard channel.
|
238 |
|
|
|
239 |
|
|
.SH TCL_MAKEFILECHANNEL
|
240 |
|
|
.PP
|
241 |
|
|
\fBTcl_MakeFileChannel\fR makes a \fBTcl_Channel\fR from an existing,
|
242 |
|
|
platform-specific, file handle.
|
243 |
|
|
The newly created channel is not registered in the supplied interpreter; to
|
244 |
|
|
register it, use \fBTcl_RegisterChannel\fR, described below.
|
245 |
|
|
If one of the standard channels, \fBstdin, stdout\fR or \fBstderr\fR was
|
246 |
|
|
previously closed, the act of creating the new channel also assigns it as a
|
247 |
|
|
replacement for the standard channel.
|
248 |
|
|
|
249 |
|
|
.SH TCL_GETCHANNEL
|
250 |
|
|
.PP
|
251 |
|
|
\fBTcl_GetChannel\fR returns a channel given the \fIchannelName\fR used to
|
252 |
|
|
create it with \fBTcl_CreateChannel\fR and a pointer to a Tcl interpreter in
|
253 |
|
|
\fIinterp\fR. If a channel by that name is not registered in that interpreter,
|
254 |
|
|
the procedure returns NULL. If the \fImode\fR argument is not NULL, it
|
255 |
|
|
points at an integer variable that will receive an OR-ed combination of
|
256 |
|
|
\fBTCL_READABLE\fR and \fBTCL_WRITABLE\fR describing whether the channel is
|
257 |
|
|
open for reading and writing.
|
258 |
|
|
|
259 |
|
|
.SH TCL_REGISTERCHANNEL
|
260 |
|
|
.PP
|
261 |
|
|
\fBTcl_RegisterChannel\fR adds a channel to the set of channels accessible
|
262 |
|
|
in \fIinterp\fR. After this call, Tcl programs executing in that
|
263 |
|
|
interpreter can refer to the channel in input or output operations using
|
264 |
|
|
the name given in the call to \fBTcl_CreateChannel\fR. After this call,
|
265 |
|
|
the channel becomes the property of the interpreter, and the caller should
|
266 |
|
|
not call \fBTcl_Close\fR for the channel; the channel will be closed
|
267 |
|
|
automatically when it is unregistered from the interpreter.
|
268 |
|
|
.PP
|
269 |
|
|
Code executing outside of any Tcl interpreter can call
|
270 |
|
|
\fBTcl_RegisterChannel\fR with \fIinterp\fR as NULL, to indicate that it
|
271 |
|
|
wishes to hold a reference to this channel. Subsequently, the channel can
|
272 |
|
|
be registered in a Tcl interpreter and it will only be closed when the
|
273 |
|
|
matching number of calls to \fBTcl_UnregisterChannel\fR have been made.
|
274 |
|
|
This allows code executing outside of any interpreter to safely hold a
|
275 |
|
|
reference to a channel that is also registered in a Tcl interpreter.
|
276 |
|
|
|
277 |
|
|
.SH TCL_UNREGISTERCHANNEL
|
278 |
|
|
.PP
|
279 |
|
|
\fBTcl_UnregisterChannel\fR removes a channel from the set of channels
|
280 |
|
|
accessible in \fIinterp\fR. After this call, Tcl programs will no longer be
|
281 |
|
|
able to use the channel's name to refer to the channel in that interpreter.
|
282 |
|
|
If this operation removed the last registration of the channel in any
|
283 |
|
|
interpreter, the channel is also closed and destroyed.
|
284 |
|
|
.PP
|
285 |
|
|
Code not associated with a Tcl interpreter can call
|
286 |
|
|
\fBTcl_UnregisterChannel\fR with \fIinterp\fR as NULL, to indicate to Tcl
|
287 |
|
|
that it no longer holds a reference to that channel. If this is the last
|
288 |
|
|
reference to the channel, it will now be closed.
|
289 |
|
|
|
290 |
|
|
.SH TCL_CLOSE
|
291 |
|
|
.PP
|
292 |
|
|
\fBTcl_Close\fR destroys the channel \fIchannel\fR, which must denote a
|
293 |
|
|
currently open channel. The channel should not be registered in any
|
294 |
|
|
interpreter when \fBTcl_Close\fR is called. Buffered output is flushed to
|
295 |
|
|
the channel's output device prior to destroying the channel, and any
|
296 |
|
|
buffered input is discarded. If this is a blocking channel, the call does
|
297 |
|
|
not return until all buffered data is successfully sent to the channel's
|
298 |
|
|
output device. If this is a nonblocking channel and there is buffered
|
299 |
|
|
output that cannot be written without blocking, the call returns
|
300 |
|
|
immediately; output is flushed in the background and the channel will be
|
301 |
|
|
closed once all of the buffered data has been output. In this case errors
|
302 |
|
|
during flushing are not reported.
|
303 |
|
|
.PP
|
304 |
|
|
If the channel was closed successfully, \fBTcl_Close\fR returns \fBTCL_OK\fR.
|
305 |
|
|
If an error occurs, \fBTcl_Close\fR returns \fBTCL_ERROR\fR and records a
|
306 |
|
|
POSIX error code that can be retrieved with \fBTcl_GetErrno\fR.
|
307 |
|
|
If the channel is being closed synchronously and an error occurs during
|
308 |
|
|
closing of the channel and \fIinterp\fR is not NULL, an error message is
|
309 |
|
|
left in \fIinterp->result\fR.
|
310 |
|
|
.PP
|
311 |
|
|
Note: it is not safe to call \fBTcl_Close\fR on a channel that has been
|
312 |
|
|
registered using \fBTcl_RegisterChannel\fR; see the documentation for
|
313 |
|
|
\fBTcl_RegisterChannel\fR, above, for details. If the channel has ever been
|
314 |
|
|
given as the \fBchan\fR argument in a call to \fBTcl_RegisterChannel\fR,
|
315 |
|
|
you should instead use \fBTcl_UnregisterChannel\fR, which will internally
|
316 |
|
|
call \fBTcl_Close\fR when all calls to \fBTcl_RegisterChannel\fR have been
|
317 |
|
|
matched by corresponding calls to \fBTcl_UnregisterChannel\fR.
|
318 |
|
|
|
319 |
|
|
.SH TCL_READ
|
320 |
|
|
.PP
|
321 |
|
|
\fBTcl_Read\fR consumes up to \fItoRead\fR bytes of data from
|
322 |
|
|
\fIchannel\fR and stores it at \fIbuf\fR.
|
323 |
|
|
The return value of \fBTcl_Read\fR is the number of characters written
|
324 |
|
|
at \fIbuf\fR.
|
325 |
|
|
The buffer produced by \fBTcl_Read\fR is not NULL terminated. Its contents
|
326 |
|
|
are valid from the zeroth position up to and excluding the position
|
327 |
|
|
indicated by the return value.
|
328 |
|
|
If an error occurs, the return value is -1 and \fBTcl_Read\fR records
|
329 |
|
|
a POSIX error code that can be retrieved with \fBTcl_GetErrno\fR.
|
330 |
|
|
.PP
|
331 |
|
|
The return value may be smaller than the value of \fItoRead\fR, indicating
|
332 |
|
|
that less data than requested was available, also called a \fIshort
|
333 |
|
|
read\fR.
|
334 |
|
|
In blocking mode, this can only happen on an end-of-file.
|
335 |
|
|
In nonblocking mode, a short read can also occur if there is not
|
336 |
|
|
enough input currently available: \fBTcl_Read\fR returns a short
|
337 |
|
|
count rather than waiting for more data.
|
338 |
|
|
.PP
|
339 |
|
|
If the channel is in blocking mode, a return value of zero indicates an end
|
340 |
|
|
of file condition. If the channel is in nonblocking mode, a return value of
|
341 |
|
|
zero indicates either that no input is currently available or an end of
|
342 |
|
|
file condition. Use \fBTcl_Eof\fR and \fBTcl_InputBlocked\fR
|
343 |
|
|
to tell which of these conditions actually occurred.
|
344 |
|
|
.PP
|
345 |
|
|
\fBTcl_Read\fR translates platform-specific end-of-line representations
|
346 |
|
|
into the canonical \fB\en\fR internal representation according to the
|
347 |
|
|
current end-of-line recognition mode. End-of-line recognition and the
|
348 |
|
|
various platform-specific modes are described in the manual entry for the
|
349 |
|
|
Tcl \fBfconfigure\fR command.
|
350 |
|
|
|
351 |
|
|
.SH TCL_GETS AND TCL_GETSOBJ
|
352 |
|
|
.PP
|
353 |
|
|
\fBTcl_Gets\fR reads a line of input from a channel and appends all of
|
354 |
|
|
the characters of the line except for the terminating end-of-line character(s)
|
355 |
|
|
to the dynamic string given by \fIdsPtr\fR.
|
356 |
|
|
The end-of-line character(s) are read and discarded.
|
357 |
|
|
.PP
|
358 |
|
|
If a line was successfully read, the return value is greater than or
|
359 |
|
|
equal to zero, and it indicates the number of characters stored
|
360 |
|
|
in the dynamic string.
|
361 |
|
|
If an error occurs, \fBTcl_Gets\fR returns -1 and records a POSIX error
|
362 |
|
|
code that can be retrieved with \fBTcl_GetErrno\fR.
|
363 |
|
|
\fBTcl_Gets\fR also returns -1 if the end of the file is reached;
|
364 |
|
|
the \fBTcl_Eof\fR procedure can be used to distinguish an error
|
365 |
|
|
from an end-of-file condition.
|
366 |
|
|
.PP
|
367 |
|
|
If the channel is in nonblocking mode, the return value can also
|
368 |
|
|
be -1 if no data was available or the data that was available
|
369 |
|
|
did not contain an end-of-line character.
|
370 |
|
|
When -1 is returned, the \fBTcl_InputBlocked\fR procedure may be
|
371 |
|
|
invoked to determine if the channel is blocked because of input
|
372 |
|
|
unavailability.
|
373 |
|
|
.PP
|
374 |
|
|
\fBTcl_GetsObj\fR is the same as \fBTcl_Gets\fR except the resulting
|
375 |
|
|
characters are appended to a Tcl object \fBlineObjPtr\fR rather than a
|
376 |
|
|
dynamic string.
|
377 |
|
|
.SH TCL_WRITE
|
378 |
|
|
.PP
|
379 |
|
|
\fBTcl_Write\fR accepts \fItoWrite\fR bytes of data at \fIbuf\fR for output
|
380 |
|
|
on \fIchannel\fR. This data may not appear on the output device
|
381 |
|
|
immediately. If the data should appear immediately, call \fBTcl_Flush\fR
|
382 |
|
|
after the call to \fBTcl_Write\fR, or set the \fB-buffering\fR option on
|
383 |
|
|
the channel to \fBnone\fR. If you wish the data to appear as soon as an end
|
384 |
|
|
of line is accepted for output, set the \fB\-buffering\fR option on the
|
385 |
|
|
channel to \fBline\fR mode.
|
386 |
|
|
.PP
|
387 |
|
|
The \fItoWrite\fR argument specifies how many bytes of data are provided in
|
388 |
|
|
the \fIbuf\fR argument. If it is negative, \fBTcl_Write\fR expects the data
|
389 |
|
|
to be NULL terminated and it outputs everything up to the NULL.
|
390 |
|
|
.PP
|
391 |
|
|
The return value of \fBTcl_Write\fR is a count of how many
|
392 |
|
|
characters were accepted for output to the channel. This is either equal to
|
393 |
|
|
\fItoWrite\fR or -1 to indicate that an error occurred.
|
394 |
|
|
If an error occurs, \fBTcl_Write\fR also records a POSIX error code
|
395 |
|
|
that may be retrieved with \fBTcl_GetErrno\fR.
|
396 |
|
|
.PP
|
397 |
|
|
Newline characters in the output data are translated to platform-specific
|
398 |
|
|
end-of-line sequences according to the \fB\-translation\fR option for
|
399 |
|
|
the channel.
|
400 |
|
|
|
401 |
|
|
.SH TCL_FLUSH
|
402 |
|
|
.PP
|
403 |
|
|
\fBTcl_Flush\fR causes all of the buffered output data for \fIchannel\fR
|
404 |
|
|
to be written to its underlying file or device as soon as possible.
|
405 |
|
|
If the channel is in blocking mode, the call does not return until
|
406 |
|
|
all the buffered data has been sent to the channel or some error occurred.
|
407 |
|
|
The call returns immediately if the channel is nonblocking; it starts
|
408 |
|
|
a background flush that will write the buffered data to the channel
|
409 |
|
|
eventually, as fast as the channel is able to absorb it.
|
410 |
|
|
.PP
|
411 |
|
|
The return value is normally \fBTCL_OK\fR.
|
412 |
|
|
If an error occurs, \fBTcl_Flush\fR returns \fBTCL_ERROR\fR and
|
413 |
|
|
records a POSIX error code that can be retrieved with \fBTcl_GetErrno\fR.
|
414 |
|
|
|
415 |
|
|
.SH TCL_SEEK
|
416 |
|
|
.PP
|
417 |
|
|
\fBTcl_Seek\fR moves the access point in \fIchannel\fR where subsequent
|
418 |
|
|
data will be read or written. Buffered output is flushed to the channel and
|
419 |
|
|
buffered input is discarded, prior to the seek operation.
|
420 |
|
|
.PP
|
421 |
|
|
\fBTcl_Seek\fR normally returns the new access point.
|
422 |
|
|
If an error occurs, \fBTcl_Seek\fR returns -1 and records a POSIX error
|
423 |
|
|
code that can be retrieved with \fBTcl_GetErrno\fR.
|
424 |
|
|
After an error, the access point may or may not have been moved.
|
425 |
|
|
|
426 |
|
|
.SH TCL_TELL
|
427 |
|
|
.PP
|
428 |
|
|
\fBTcl_Tell\fR returns the current access point for a channel. The returned
|
429 |
|
|
value is -1 if the channel does not support seeking.
|
430 |
|
|
|
431 |
|
|
.SH TCL_GETCHANNELOPTION
|
432 |
|
|
.PP
|
433 |
|
|
\fBTcl_GetChannelOption\fR retrieves, in \fIdsPtr\fR, the value of one of
|
434 |
|
|
the options currently in effect for a channel, or a list of all options and
|
435 |
|
|
their values. The \fIchannel\fR argument identifies the channel for which
|
436 |
|
|
to query an option or retrieve all options and their values.
|
437 |
|
|
If \fIoptionName\fR is not NULL, it is the name of the
|
438 |
|
|
option to query; the option's value is copied to the Tcl dynamic string
|
439 |
|
|
denoted by \fIoptionValue\fR. If
|
440 |
|
|
\fIoptionName\fR is NULL, the function stores an alternating list of option
|
441 |
|
|
names and their values in \fIoptionValue\fR, using a series of calls to
|
442 |
|
|
\fBTcl_DStringAppendElement\fR. The various preexisting options and
|
443 |
|
|
their possible values are described in the manual entry for the Tcl
|
444 |
|
|
\fBfconfigure\fR command. Other options can be added by each channel type.
|
445 |
|
|
These channel type specific options are described in the manual entry for
|
446 |
|
|
the Tcl command that creates a channel of that type; for example, the
|
447 |
|
|
additional options for TCP based channels are described in the manual entry
|
448 |
|
|
for the Tcl \fBsocket\fR command.
|
449 |
|
|
The procedure normally returns \fBTCL_OK\fR. If an error occurs, it returns
|
450 |
|
|
\fBTCL_ERROR\fR and calls \fBTcl_SetErrno\fR to store an appropriate POSIX
|
451 |
|
|
error code.
|
452 |
|
|
|
453 |
|
|
.SH TCL_SETCHANNELOPTION
|
454 |
|
|
.PP
|
455 |
|
|
\fBTcl_SetChannelOption\fR sets a new value for an option on \fIchannel\fR.
|
456 |
|
|
\fIOptionName\fR is the option to set and \fInewValue\fR is the value to
|
457 |
|
|
set.
|
458 |
|
|
The procedure normally returns \fBTCL_OK\fR. If an error occurs,
|
459 |
|
|
it returns \fBTCL_ERROR\fR; in addition, if \fIinterp\fR is non-NULL,
|
460 |
|
|
\fBTcl_SetChannelOption\fR leaves an error message in \fIinterp->result\fR.
|
461 |
|
|
|
462 |
|
|
.SH TCL_EOF
|
463 |
|
|
.PP
|
464 |
|
|
\fBTcl_Eof\fR returns a nonzero value if \fIchannel\fR encountered
|
465 |
|
|
an end of file during the last input operation.
|
466 |
|
|
|
467 |
|
|
.SH TCL_INPUTBLOCKED
|
468 |
|
|
.PP
|
469 |
|
|
\fBTcl_InputBlocked\fR returns a nonzero value if \fIchannel\fR is in
|
470 |
|
|
nonblocking mode and the last input operation returned less data than
|
471 |
|
|
requested because there was insufficient data available.
|
472 |
|
|
The call always returns zero if the channel is in blocking mode.
|
473 |
|
|
|
474 |
|
|
.SH TCL_INPUTBUFFERED
|
475 |
|
|
.PP
|
476 |
|
|
\fBTcl_InputBuffered\fR returns the number of bytes of input currently
|
477 |
|
|
buffered in the internal buffers for a channel. If the channel is not open
|
478 |
|
|
for reading, this function always returns zero.
|
479 |
|
|
|
480 |
|
|
.VS
|
481 |
|
|
.SH "PLATFORM ISSUES"
|
482 |
|
|
.PP
|
483 |
|
|
The handles returned from \fBTcl_GetChannelHandle\fR depend on the
|
484 |
|
|
platform and the channel type. On Unix platforms, the handle is
|
485 |
|
|
always a Unix file descriptor as returned from the \fBopen\fR system
|
486 |
|
|
call. On Windows platforms, the handle is a file \fBHANDLE\fR when
|
487 |
|
|
the channel was created with \fBTcl_OpenFileChannel\fR,
|
488 |
|
|
\fBTcl_OpenCommandChannel\fR, or \fBTcl_MakeFileChannel\fR. Other
|
489 |
|
|
channel types may return a different type of handle on Windows
|
490 |
|
|
platforms. On the Macintosh platform, the handle is a file reference
|
491 |
|
|
number as returned from \fBHOpenDF\fR.
|
492 |
|
|
.VE
|
493 |
|
|
|
494 |
|
|
.SH "SEE ALSO"
|
495 |
|
|
DString(3), fconfigure(n), filename(n), fopen(2), Tcl_CreateChannel(3)
|
496 |
|
|
|
497 |
|
|
.SH KEYWORDS
|
498 |
|
|
access point, blocking, buffered I/O, channel, channel driver, end of file,
|
499 |
|
|
flush, input, nonblocking, output, read, seek, write
|