1 | '\" |
---|
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.36 2007/12/13 15:22:31 dgp Exp $ |
---|
8 | .so man.macros |
---|
9 | .TH Tcl_OpenFileChannel 3 8.3 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_GetChannelNames, Tcl_GetChannelNamesEx, Tcl_RegisterChannel, Tcl_UnregisterChannel, Tcl_DetachChannel, Tcl_IsStandardChannel, Tcl_Close, Tcl_ReadChars, Tcl_Read, Tcl_GetsObj, Tcl_Gets, Tcl_WriteObj, Tcl_WriteChars, Tcl_Write, Tcl_Flush, Tcl_Seek, Tcl_Tell, Tcl_TruncateChannel, Tcl_GetChannelOption, Tcl_SetChannelOption, Tcl_Eof, Tcl_InputBlocked, Tcl_InputBuffered, Tcl_OutputBuffered, Tcl_Ungets, Tcl_ReadRaw, Tcl_WriteRaw \- buffered I/O facilities using channels |
---|
14 | .SH SYNOPSIS |
---|
15 | .nf |
---|
16 | \fB#include <tcl.h>\fR |
---|
17 | .sp |
---|
18 | Tcl_Channel |
---|
19 | \fBTcl_OpenFileChannel\fR(\fIinterp, fileName, mode, permissions\fR) |
---|
20 | .sp |
---|
21 | Tcl_Channel |
---|
22 | \fBTcl_OpenCommandChannel\fR(\fIinterp, argc, argv, flags\fR) |
---|
23 | .sp |
---|
24 | Tcl_Channel |
---|
25 | \fBTcl_MakeFileChannel\fR(\fIhandle, readOrWrite\fR) |
---|
26 | .sp |
---|
27 | Tcl_Channel |
---|
28 | \fBTcl_GetChannel\fR(\fIinterp, channelName, modePtr\fR) |
---|
29 | .sp |
---|
30 | int |
---|
31 | \fBTcl_GetChannelNames\fR(\fIinterp\fR) |
---|
32 | .sp |
---|
33 | int |
---|
34 | \fBTcl_GetChannelNamesEx\fR(\fIinterp, pattern\fR) |
---|
35 | .sp |
---|
36 | void |
---|
37 | \fBTcl_RegisterChannel\fR(\fIinterp, channel\fR) |
---|
38 | .sp |
---|
39 | int |
---|
40 | \fBTcl_UnregisterChannel\fR(\fIinterp, channel\fR) |
---|
41 | .sp |
---|
42 | int |
---|
43 | \fBTcl_DetachChannel\fR(\fIinterp, channel\fR) |
---|
44 | .sp |
---|
45 | int |
---|
46 | \fBTcl_IsStandardChannel\fR(\fIchannel\fR) |
---|
47 | .sp |
---|
48 | int |
---|
49 | \fBTcl_Close\fR(\fIinterp, channel\fR) |
---|
50 | .sp |
---|
51 | int |
---|
52 | \fBTcl_ReadChars\fR(\fIchannel, readObjPtr, charsToRead, appendFlag\fR) |
---|
53 | .sp |
---|
54 | int |
---|
55 | \fBTcl_Read\fR(\fIchannel, readBuf, bytesToRead\fR) |
---|
56 | .sp |
---|
57 | int |
---|
58 | \fBTcl_GetsObj\fR(\fIchannel, lineObjPtr\fR) |
---|
59 | .sp |
---|
60 | int |
---|
61 | \fBTcl_Gets\fR(\fIchannel, lineRead\fR) |
---|
62 | .sp |
---|
63 | int |
---|
64 | \fBTcl_Ungets\fR(\fIchannel, input, inputLen, addAtEnd\fR) |
---|
65 | .sp |
---|
66 | int |
---|
67 | \fBTcl_WriteObj\fR(\fIchannel, writeObjPtr\fR) |
---|
68 | .sp |
---|
69 | int |
---|
70 | \fBTcl_WriteChars\fR(\fIchannel, charBuf, bytesToWrite\fR) |
---|
71 | .sp |
---|
72 | int |
---|
73 | \fBTcl_Write\fR(\fIchannel, byteBuf, bytesToWrite\fR) |
---|
74 | .sp |
---|
75 | int |
---|
76 | \fBTcl_ReadRaw\fR(\fIchannel, readBuf, bytesToRead\fR) |
---|
77 | .sp |
---|
78 | int |
---|
79 | \fBTcl_WriteRaw\fR(\fIchannel, byteBuf, bytesToWrite\fR) |
---|
80 | .sp |
---|
81 | int |
---|
82 | \fBTcl_Eof\fR(\fIchannel\fR) |
---|
83 | .sp |
---|
84 | int |
---|
85 | \fBTcl_Flush\fR(\fIchannel\fR) |
---|
86 | .sp |
---|
87 | int |
---|
88 | \fBTcl_InputBlocked\fR(\fIchannel\fR) |
---|
89 | .sp |
---|
90 | int |
---|
91 | \fBTcl_InputBuffered\fR(\fIchannel\fR) |
---|
92 | .sp |
---|
93 | int |
---|
94 | \fBTcl_OutputBuffered\fR(\fIchannel\fR) |
---|
95 | .sp |
---|
96 | Tcl_WideInt |
---|
97 | \fBTcl_Seek\fR(\fIchannel, offset, seekMode\fR) |
---|
98 | .sp |
---|
99 | Tcl_WideInt |
---|
100 | \fBTcl_Tell\fR(\fIchannel\fR) |
---|
101 | .sp |
---|
102 | .VS 8.5 |
---|
103 | int |
---|
104 | \fBTcl_TruncateChannel\fR(\fIchannel, length\fR) |
---|
105 | .VE 8.5 |
---|
106 | .sp |
---|
107 | int |
---|
108 | \fBTcl_GetChannelOption\fR(\fIinterp, channel, optionName, optionValue\fR) |
---|
109 | .sp |
---|
110 | int |
---|
111 | \fBTcl_SetChannelOption\fR(\fIinterp, channel, optionName, newValue\fR) |
---|
112 | .sp |
---|
113 | .SH ARGUMENTS |
---|
114 | .AS Tcl_DString *channelName in/out |
---|
115 | .AP Tcl_Interp *interp in |
---|
116 | Used for error reporting and to look up a channel registered in it. |
---|
117 | .AP "const char" *fileName in |
---|
118 | The name of a local or network file. |
---|
119 | .AP "const char" *mode in |
---|
120 | Specifies how the file is to be accessed. May have any of the values |
---|
121 | allowed for the \fImode\fR argument to the Tcl \fBopen\fR command. |
---|
122 | .AP int permissions in |
---|
123 | POSIX-style permission flags such as 0644. If a new file is created, these |
---|
124 | permissions will be set on the created file. |
---|
125 | .AP int argc in |
---|
126 | The number of elements in \fIargv\fR. |
---|
127 | .AP "const char" **argv in |
---|
128 | Arguments for constructing a command pipeline. These values have the same |
---|
129 | meaning as the non-switch arguments to the Tcl \fBexec\fR command. |
---|
130 | .AP int flags in |
---|
131 | Specifies the disposition of the stdio handles in pipeline: OR-ed |
---|
132 | combination of \fBTCL_STDIN\fR, \fBTCL_STDOUT\fR, \fBTCL_STDERR\fR, and |
---|
133 | \fBTCL_ENFORCE_MODE\fR. If \fBTCL_STDIN\fR is set, stdin for the first child |
---|
134 | in the pipe is the pipe channel, otherwise it is the same as the standard |
---|
135 | input of the invoking process; likewise for \fBTCL_STDOUT\fR and |
---|
136 | \fBTCL_STDERR\fR. If \fBTCL_ENFORCE_MODE\fR is not set, then the pipe can |
---|
137 | redirect stdio handles to override the stdio handles for which |
---|
138 | \fBTCL_STDIN\fR, \fBTCL_STDOUT\fR and \fBTCL_STDERR\fR have been set. If it |
---|
139 | is set, then such redirections cause an error. |
---|
140 | .AP ClientData handle in |
---|
141 | Operating system specific handle for I/O to a file. For Unix this is a |
---|
142 | file descriptor, for Windows it is a HANDLE. |
---|
143 | .AP int readOrWrite in |
---|
144 | OR-ed combination of \fBTCL_READABLE\fR and \fBTCL_WRITABLE\fR to indicate |
---|
145 | what operations are valid on \fIhandle\fR. |
---|
146 | .AP "const char" *channelName in |
---|
147 | The name of the channel. |
---|
148 | .AP int *modePtr out |
---|
149 | Points at an integer variable that will receive an OR-ed combination of |
---|
150 | \fBTCL_READABLE\fR and \fBTCL_WRITABLE\fR denoting whether the channel is |
---|
151 | open for reading and writing. |
---|
152 | .AP "const char" *pattern in |
---|
153 | The pattern to match on, passed to Tcl_StringMatch, or NULL. |
---|
154 | .AP Tcl_Channel channel in |
---|
155 | A Tcl channel for input or output. Must have been the return value |
---|
156 | from a procedure such as \fBTcl_OpenFileChannel\fR. |
---|
157 | .AP Tcl_Obj *readObjPtr in/out |
---|
158 | A pointer to a Tcl Object in which to store the characters read from the |
---|
159 | channel. |
---|
160 | .AP int charsToRead in |
---|
161 | The number of characters to read from the channel. If the channel's encoding |
---|
162 | is \fBbinary\fR, this is equivalent to the number of bytes to read from the |
---|
163 | channel. |
---|
164 | .AP int appendFlag in |
---|
165 | If non-zero, data read from the channel will be appended to the object. |
---|
166 | Otherwise, the data will replace the existing contents of the object. |
---|
167 | .AP char *readBuf out |
---|
168 | A buffer in which to store the bytes read from the channel. |
---|
169 | .AP int bytesToRead in |
---|
170 | The number of bytes to read from the channel. The buffer \fIreadBuf\fR must |
---|
171 | be large enough to hold this many bytes. |
---|
172 | .AP Tcl_Obj *lineObjPtr in/out |
---|
173 | A pointer to a Tcl object in which to store the line read from the |
---|
174 | channel. The line read will be appended to the current value of the |
---|
175 | object. |
---|
176 | .AP Tcl_DString *lineRead in/out |
---|
177 | A pointer to a Tcl dynamic string in which to store the line read from the |
---|
178 | channel. Must have been initialized by the caller. The line read will be |
---|
179 | appended to any data already in the dynamic string. |
---|
180 | .AP "const char" *input in |
---|
181 | The input to add to a channel buffer. |
---|
182 | .AP int inputLen in |
---|
183 | Length of the input |
---|
184 | .AP int addAtEnd in |
---|
185 | Flag indicating whether the input should be added to the end or |
---|
186 | beginning of the channel buffer. |
---|
187 | .AP Tcl_Obj *writeObjPtr in |
---|
188 | A pointer to a Tcl Object whose contents will be output to the channel. |
---|
189 | .AP "const char" *charBuf in |
---|
190 | A buffer containing the characters to output to the channel. |
---|
191 | .AP "const char" *byteBuf in |
---|
192 | A buffer containing the bytes to output to the channel. |
---|
193 | .AP int bytesToWrite in |
---|
194 | The number of bytes to consume from \fIcharBuf\fR or \fIbyteBuf\fR and |
---|
195 | output to the channel. |
---|
196 | .AP Tcl_WideInt offset in |
---|
197 | How far to move the access point in the channel at which the next input or |
---|
198 | output operation will be applied, measured in bytes from the position |
---|
199 | given by \fIseekMode\fR. May be either positive or negative. |
---|
200 | .AP int seekMode in |
---|
201 | Relative to which point to seek; used with \fIoffset\fR to calculate the new |
---|
202 | access point for the channel. Legal values are \fBSEEK_SET\fR, |
---|
203 | \fBSEEK_CUR\fR, and \fBSEEK_END\fR. |
---|
204 | .AP Tcl_WideInt length in |
---|
205 | The (non-negative) length to truncate the channel the channel to. |
---|
206 | .AP "const char" *optionName in |
---|
207 | The name of an option applicable to this channel, such as \fB\-blocking\fR. |
---|
208 | May have any of the values accepted by the \fBfconfigure\fR command. |
---|
209 | .AP Tcl_DString *optionValue in |
---|
210 | Where to store the value of an option or a list of all options and their |
---|
211 | values. Must have been initialized by the caller. |
---|
212 | .AP "const char" *newValue in |
---|
213 | New value for the option given by \fIoptionName\fR. |
---|
214 | .BE |
---|
215 | |
---|
216 | .SH DESCRIPTION |
---|
217 | .PP |
---|
218 | The Tcl channel mechanism provides a device-independent and |
---|
219 | platform-independent mechanism for performing buffered input |
---|
220 | and output operations on a variety of file, socket, and device |
---|
221 | types. |
---|
222 | The channel mechanism is extensible to new channel types, by |
---|
223 | providing a low-level channel driver for the new type; the channel driver |
---|
224 | interface is described in the manual entry for \fBTcl_CreateChannel\fR. The |
---|
225 | channel mechanism provides a buffering scheme modeled after |
---|
226 | Unix's standard I/O, and it also allows for nonblocking I/O on |
---|
227 | channels. |
---|
228 | .PP |
---|
229 | The procedures described in this manual entry comprise the C APIs of the |
---|
230 | generic layer of the channel architecture. For a description of the channel |
---|
231 | driver architecture and how to implement channel drivers for new types of |
---|
232 | channels, see the manual entry for \fBTcl_CreateChannel\fR. |
---|
233 | |
---|
234 | .SH TCL_OPENFILECHANNEL |
---|
235 | .PP |
---|
236 | \fBTcl_OpenFileChannel\fR opens a file specified by \fIfileName\fR and |
---|
237 | returns a channel handle that can be used to perform input and output on |
---|
238 | the file. This API is modeled after the \fBfopen\fR procedure of |
---|
239 | the Unix standard I/O library. |
---|
240 | The syntax and meaning of all arguments is similar to those |
---|
241 | given in the Tcl \fBopen\fR command when opening a file. |
---|
242 | If an error occurs while opening the channel, \fBTcl_OpenFileChannel\fR |
---|
243 | returns NULL and records a POSIX error code that can be |
---|
244 | retrieved with \fBTcl_GetErrno\fR. |
---|
245 | In addition, if \fIinterp\fR is non-NULL, \fBTcl_OpenFileChannel\fR |
---|
246 | leaves an error message in \fIinterp\fR's result after any error. |
---|
247 | As of Tcl 8.4, the object-based API \fBTcl_FSOpenFileChannel\fR should |
---|
248 | be used in preference to \fBTcl_OpenFileChannel\fR wherever possible. |
---|
249 | .PP |
---|
250 | The newly created channel is not registered in the supplied interpreter; to |
---|
251 | register it, use \fBTcl_RegisterChannel\fR, described below. |
---|
252 | If one of the standard channels, \fBstdin, stdout\fR or \fBstderr\fR was |
---|
253 | previously closed, the act of creating the new channel also assigns it as a |
---|
254 | replacement for the standard channel. |
---|
255 | |
---|
256 | .SH TCL_OPENCOMMANDCHANNEL |
---|
257 | .PP |
---|
258 | \fBTcl_OpenCommandChannel\fR provides a C-level interface to the |
---|
259 | functions of the \fBexec\fR and \fBopen\fR commands. |
---|
260 | It creates a sequence of subprocesses specified |
---|
261 | by the \fIargv\fR and \fIargc\fR arguments and returns a channel that can |
---|
262 | be used to communicate with these subprocesses. |
---|
263 | The \fIflags\fR argument indicates what sort of communication will |
---|
264 | exist with the command pipeline. |
---|
265 | .PP |
---|
266 | If the \fBTCL_STDIN\fR flag is set then the standard input for the |
---|
267 | first subprocess will be tied to the channel: writing to the channel |
---|
268 | will provide input to the subprocess. If \fBTCL_STDIN\fR is not set, |
---|
269 | then standard input for the first subprocess will be the same as this |
---|
270 | application's standard input. If \fBTCL_STDOUT\fR is set then |
---|
271 | standard output from the last subprocess can be read from the channel; |
---|
272 | otherwise it goes to this application's standard output. If |
---|
273 | \fBTCL_STDERR\fR is set, standard error output for all subprocesses is |
---|
274 | returned to the channel and results in an error when the channel is |
---|
275 | closed; otherwise it goes to this application's standard error. If |
---|
276 | \fBTCL_ENFORCE_MODE\fR is not set, then \fIargc\fR and \fIargv\fR can |
---|
277 | redirect the stdio handles to override \fBTCL_STDIN\fR, |
---|
278 | \fBTCL_STDOUT\fR, and \fBTCL_STDERR\fR; if it is set, then it is an |
---|
279 | error for argc and argv to override stdio channels for which |
---|
280 | \fBTCL_STDIN\fR, \fBTCL_STDOUT\fR, and \fBTCL_STDERR\fR have been set. |
---|
281 | .PP |
---|
282 | If an error occurs while opening the channel, \fBTcl_OpenCommandChannel\fR |
---|
283 | returns NULL and records a POSIX error code that can be retrieved with |
---|
284 | \fBTcl_GetErrno\fR. |
---|
285 | In addition, \fBTcl_OpenCommandChannel\fR leaves an error message in |
---|
286 | the interpreter's result if \fIinterp\fR is not NULL. |
---|
287 | .PP |
---|
288 | The newly created channel is not registered in the supplied interpreter; to |
---|
289 | register it, use \fBTcl_RegisterChannel\fR, described below. |
---|
290 | If one of the standard channels, \fBstdin, stdout\fR or \fBstderr\fR was |
---|
291 | previously closed, the act of creating the new channel also assigns it as a |
---|
292 | replacement for the standard channel. |
---|
293 | |
---|
294 | .SH TCL_MAKEFILECHANNEL |
---|
295 | .PP |
---|
296 | \fBTcl_MakeFileChannel\fR makes a \fBTcl_Channel\fR from an existing, |
---|
297 | platform-specific, file handle. |
---|
298 | The newly created channel is not registered in the supplied interpreter; to |
---|
299 | register it, use \fBTcl_RegisterChannel\fR, described below. |
---|
300 | If one of the standard channels, \fBstdin, stdout\fR or \fBstderr\fR was |
---|
301 | previously closed, the act of creating the new channel also assigns it as a |
---|
302 | replacement for the standard channel. |
---|
303 | |
---|
304 | .SH TCL_GETCHANNEL |
---|
305 | .PP |
---|
306 | \fBTcl_GetChannel\fR returns a channel given the \fIchannelName\fR used to |
---|
307 | create it with \fBTcl_CreateChannel\fR and a pointer to a Tcl interpreter in |
---|
308 | \fIinterp\fR. If a channel by that name is not registered in that interpreter, |
---|
309 | the procedure returns NULL. If the \fImodePtr\fR argument is not NULL, it |
---|
310 | points at an integer variable that will receive an OR-ed combination of |
---|
311 | \fBTCL_READABLE\fR and \fBTCL_WRITABLE\fR describing whether the channel is |
---|
312 | open for reading and writing. |
---|
313 | .PP |
---|
314 | \fBTcl_GetChannelNames\fR and \fBTcl_GetChannelNamesEx\fR write the |
---|
315 | names of the registered channels to the interpreter's result as a |
---|
316 | list object. \fBTcl_GetChannelNamesEx\fR will filter these names |
---|
317 | according to the \fIpattern\fR. If \fIpattern\fR is NULL, then it |
---|
318 | will not do any filtering. The return value is \fBTCL_OK\fR if no |
---|
319 | errors occurred writing to the result, otherwise it is \fBTCL_ERROR\fR, |
---|
320 | and the error message is left in the interpreter's result. |
---|
321 | |
---|
322 | .SH TCL_REGISTERCHANNEL |
---|
323 | .PP |
---|
324 | \fBTcl_RegisterChannel\fR adds a channel to the set of channels accessible |
---|
325 | in \fIinterp\fR. After this call, Tcl programs executing in that |
---|
326 | interpreter can refer to the channel in input or output operations using |
---|
327 | the name given in the call to \fBTcl_CreateChannel\fR. After this call, |
---|
328 | the channel becomes the property of the interpreter, and the caller should |
---|
329 | not call \fBTcl_Close\fR for the channel; the channel will be closed |
---|
330 | automatically when it is unregistered from the interpreter. |
---|
331 | .PP |
---|
332 | Code executing outside of any Tcl interpreter can call |
---|
333 | \fBTcl_RegisterChannel\fR with \fIinterp\fR as NULL, to indicate that it |
---|
334 | wishes to hold a reference to this channel. Subsequently, the channel can |
---|
335 | be registered in a Tcl interpreter and it will only be closed when the |
---|
336 | matching number of calls to \fBTcl_UnregisterChannel\fR have been made. |
---|
337 | This allows code executing outside of any interpreter to safely hold a |
---|
338 | reference to a channel that is also registered in a Tcl interpreter. |
---|
339 | .PP |
---|
340 | This procedure interacts with the code managing the standard |
---|
341 | channels. If no standard channels were initialized before the first |
---|
342 | call to \fBTcl_RegisterChannel\fR, they will get initialized by that |
---|
343 | call. See \fBTcl_StandardChannels\fR for a general treatise about |
---|
344 | standard channels and the behaviour of the Tcl library with regard to |
---|
345 | them. |
---|
346 | |
---|
347 | .SH TCL_UNREGISTERCHANNEL |
---|
348 | .PP |
---|
349 | \fBTcl_UnregisterChannel\fR removes a channel from the set of channels |
---|
350 | accessible in \fIinterp\fR. After this call, Tcl programs will no longer be |
---|
351 | able to use the channel's name to refer to the channel in that interpreter. |
---|
352 | If this operation removed the last registration of the channel in any |
---|
353 | interpreter, the channel is also closed and destroyed. |
---|
354 | .PP |
---|
355 | Code not associated with a Tcl interpreter can call |
---|
356 | \fBTcl_UnregisterChannel\fR with \fIinterp\fR as NULL, to indicate to Tcl |
---|
357 | that it no longer holds a reference to that channel. If this is the last |
---|
358 | reference to the channel, it will now be closed. \fBTcl_UnregisterChannel\fR |
---|
359 | is very similar to \fBTcl_DetachChannel\fR except that it will also |
---|
360 | close the channel if no further references to it exist. |
---|
361 | |
---|
362 | .SH TCL_DETACHCHANNEL |
---|
363 | .PP |
---|
364 | \fBTcl_DetachChannel\fR removes a channel from the set of channels |
---|
365 | accessible in \fIinterp\fR. After this call, Tcl programs will no longer be |
---|
366 | able to use the channel's name to refer to the channel in that interpreter. |
---|
367 | Beyond that, this command has no further effect. It cannot be used on |
---|
368 | the standard channels (stdout, stderr, stdin), and will return |
---|
369 | \fBTCL_ERROR\fR if passed one of those channels. |
---|
370 | .PP |
---|
371 | Code not associated with a Tcl interpreter can call |
---|
372 | \fBTcl_DetachChannel\fR with \fIinterp\fR as NULL, to indicate to Tcl |
---|
373 | that it no longer holds a reference to that channel. If this is the last |
---|
374 | reference to the channel, unlike \fBTcl_UnregisterChannel\fR, |
---|
375 | it will not be closed. |
---|
376 | |
---|
377 | .SH TCL_ISSTANDARDCHANNEL |
---|
378 | .PP |
---|
379 | \fBTcl_IsStandardChannel\fR tests whether a channel is one of the |
---|
380 | three standard channels, stdin, stdout or stderr. If so, it returns |
---|
381 | 1, otherwise 0. |
---|
382 | .PP |
---|
383 | No attempt is made to check whether the given channel or the standard |
---|
384 | channels are initialized or otherwise valid. |
---|
385 | |
---|
386 | .SH TCL_CLOSE |
---|
387 | .PP |
---|
388 | \fBTcl_Close\fR destroys the channel \fIchannel\fR, which must denote a |
---|
389 | currently open channel. The channel should not be registered in any |
---|
390 | interpreter when \fBTcl_Close\fR is called. Buffered output is flushed to |
---|
391 | the channel's output device prior to destroying the channel, and any |
---|
392 | buffered input is discarded. If this is a blocking channel, the call does |
---|
393 | not return until all buffered data is successfully sent to the channel's |
---|
394 | output device. If this is a nonblocking channel and there is buffered |
---|
395 | output that cannot be written without blocking, the call returns |
---|
396 | immediately; output is flushed in the background and the channel will be |
---|
397 | closed once all of the buffered data has been output. In this case errors |
---|
398 | during flushing are not reported. |
---|
399 | .PP |
---|
400 | If the channel was closed successfully, \fBTcl_Close\fR returns \fBTCL_OK\fR. |
---|
401 | If an error occurs, \fBTcl_Close\fR returns \fBTCL_ERROR\fR and records a |
---|
402 | POSIX error code that can be retrieved with \fBTcl_GetErrno\fR. |
---|
403 | If the channel is being closed synchronously and an error occurs during |
---|
404 | closing of the channel and \fIinterp\fR is not NULL, an error message is |
---|
405 | left in the interpreter's result. |
---|
406 | .PP |
---|
407 | Note: it is not safe to call \fBTcl_Close\fR on a channel that has been |
---|
408 | registered using \fBTcl_RegisterChannel\fR; see the documentation for |
---|
409 | \fBTcl_RegisterChannel\fR, above, for details. If the channel has ever |
---|
410 | been given as the \fBchan\fR argument in a call to |
---|
411 | \fBTcl_RegisterChannel\fR, you should instead use |
---|
412 | \fBTcl_UnregisterChannel\fR, which will internally call \fBTcl_Close\fR |
---|
413 | when all calls to \fBTcl_RegisterChannel\fR have been matched by |
---|
414 | corresponding calls to \fBTcl_UnregisterChannel\fR. |
---|
415 | |
---|
416 | .SH "TCL_READCHARS AND TCL_READ" |
---|
417 | .PP |
---|
418 | \fBTcl_ReadChars\fR consumes bytes from \fIchannel\fR, converting the bytes |
---|
419 | to UTF-8 based on the channel's encoding and storing the produced data in |
---|
420 | \fIreadObjPtr\fR's string representation. The return value of |
---|
421 | \fBTcl_ReadChars\fR is the number of characters, up to \fIcharsToRead\fR, |
---|
422 | that were stored in \fIreadObjPtr\fR. If an error occurs while reading, the |
---|
423 | return value is \-1 and \fBTcl_ReadChars\fR records a POSIX error code that |
---|
424 | can be retrieved with \fBTcl_GetErrno\fR. |
---|
425 | .PP |
---|
426 | Setting \fIcharsToRead\fR to \fB\-1\fR will cause the command to read |
---|
427 | all characters currently available (non-blocking) or everything until |
---|
428 | eof (blocking mode). |
---|
429 | .PP |
---|
430 | The return value may be smaller than the value to read, indicating that less |
---|
431 | data than requested was available. This is called a \fIshort read\fR. In |
---|
432 | blocking mode, this can only happen on an end-of-file. In nonblocking mode, |
---|
433 | a short read can also occur if there is not enough input currently |
---|
434 | available: \fBTcl_ReadChars\fR returns a short count rather than waiting |
---|
435 | for more data. |
---|
436 | .PP |
---|
437 | If the channel is in blocking mode, a return value of zero indicates an |
---|
438 | end-of-file condition. If the channel is in nonblocking mode, a return |
---|
439 | value of zero indicates either that no input is currently available or an |
---|
440 | end-of-file condition. Use \fBTcl_Eof\fR and \fBTcl_InputBlocked\fR to tell |
---|
441 | which of these conditions actually occurred. |
---|
442 | .PP |
---|
443 | \fBTcl_ReadChars\fR translates the various end-of-line representations into |
---|
444 | the canonical \fB\en\fR internal representation according to the current |
---|
445 | end-of-line recognition mode. End-of-line recognition and the various |
---|
446 | platform-specific modes are described in the manual entry for the Tcl |
---|
447 | \fBfconfigure\fR command. |
---|
448 | .PP |
---|
449 | As a performance optimization, when reading from a channel with the encoding |
---|
450 | \fBbinary\fR, the bytes are not converted to UTF-8 as they are read. |
---|
451 | Instead, they are stored in \fIreadObjPtr\fR's internal representation as a |
---|
452 | byte-array object. The string representation of this object will only be |
---|
453 | constructed if it is needed (e.g., because of a call to |
---|
454 | \fBTcl_GetStringFromObj\fR). In this way, byte-oriented data can be read |
---|
455 | from a channel, manipulated by calling \fBTcl_GetByteArrayFromObj\fR and |
---|
456 | related functions, and then written to a channel without the expense of ever |
---|
457 | converting to or from UTF-8. |
---|
458 | .PP |
---|
459 | \fBTcl_Read\fR is similar to \fBTcl_ReadChars\fR, except that it does not do |
---|
460 | encoding conversions, regardless of the channel's encoding. It is deprecated |
---|
461 | and exists for backwards compatibility with non-internationalized Tcl |
---|
462 | extensions. It consumes bytes from \fIchannel\fR and stores them in |
---|
463 | \fIreadBuf\fR, performing end-of-line translations on the way. The return value |
---|
464 | of \fBTcl_Read\fR is the number of bytes, up to \fIbytesToRead\fR, written in |
---|
465 | \fIreadBuf\fR. The buffer produced by \fBTcl_Read\fR is not null-terminated. |
---|
466 | Its contents are valid from the zeroth position up to and excluding the |
---|
467 | position indicated by the return value. |
---|
468 | .PP |
---|
469 | \fBTcl_ReadRaw\fR is the same as \fBTcl_Read\fR but does not |
---|
470 | compensate for stacking. While \fBTcl_Read\fR (and the other functions |
---|
471 | in the API) always get their data from the topmost channel in the |
---|
472 | stack the supplied channel is part of, \fBTcl_ReadRaw\fR does |
---|
473 | not. Thus this function is \fBonly\fR usable for transformational |
---|
474 | channel drivers, i.e. drivers used in the middle of a stack of |
---|
475 | channels, to move data from the channel below into the transformation. |
---|
476 | |
---|
477 | .SH "TCL_GETSOBJ AND TCL_GETS" |
---|
478 | .PP |
---|
479 | \fBTcl_GetsObj\fR consumes bytes from \fIchannel\fR, converting the bytes to |
---|
480 | UTF-8 based on the channel's encoding, until a full line of input has been |
---|
481 | seen. If the channel's encoding is \fBbinary\fR, each byte read from the |
---|
482 | channel is treated as an individual Unicode character. All of the |
---|
483 | characters of the line except for the terminating end-of-line character(s) |
---|
484 | are appended to \fIlineObjPtr\fR's string representation. The end-of-line |
---|
485 | character(s) are read and discarded. |
---|
486 | .PP |
---|
487 | If a line was successfully read, the return value is greater than or equal |
---|
488 | to zero and indicates the number of bytes stored in \fIlineObjPtr\fR. If an |
---|
489 | error occurs, \fBTcl_GetsObj\fR returns \-1 and records a POSIX error code |
---|
490 | that can be retrieved with \fBTcl_GetErrno\fR. \fBTcl_GetsObj\fR also |
---|
491 | returns \-1 if the end of the file is reached; the \fBTcl_Eof\fR procedure |
---|
492 | can be used to distinguish an error from an end-of-file condition. |
---|
493 | .PP |
---|
494 | If the channel is in nonblocking mode, the return value can also be \-1 if |
---|
495 | no data was available or the data that was available did not contain an |
---|
496 | end-of-line character. When \-1 is returned, the \fBTcl_InputBlocked\fR |
---|
497 | procedure may be invoked to determine if the channel is blocked because |
---|
498 | of input unavailability. |
---|
499 | .PP |
---|
500 | \fBTcl_Gets\fR is the same as \fBTcl_GetsObj\fR except the resulting |
---|
501 | characters are appended to the dynamic string given by |
---|
502 | \fIlineRead\fR rather than a Tcl object. |
---|
503 | |
---|
504 | .SH "TCL_UNGETS" |
---|
505 | .PP |
---|
506 | \fBTcl_Ungets\fR is used to add data to the input queue of a channel, |
---|
507 | at either the head or tail of the queue. The pointer \fIinput\fR points |
---|
508 | to the data that is to be added. The length of the input to add is given |
---|
509 | by \fIinputLen\fR. A non-zero value of \fIaddAtEnd\fR indicates that the |
---|
510 | data is to be added at the end of queue; otherwise it will be added at the |
---|
511 | head of the queue. If \fIchannel\fR has a |
---|
512 | .QW sticky |
---|
513 | EOF set, no data will be |
---|
514 | added to the input queue. \fBTcl_Ungets\fR returns \fIinputLen\fR or |
---|
515 | \-1 if an error occurs. |
---|
516 | |
---|
517 | .SH "TCL_WRITECHARS, TCL_WRITEOBJ, AND TCL_WRITE" |
---|
518 | .PP |
---|
519 | \fBTcl_WriteChars\fR accepts \fIbytesToWrite\fR bytes of character data at |
---|
520 | \fIcharBuf\fR. The UTF-8 characters in the buffer are converted to the |
---|
521 | channel's encoding and queued for output to \fIchannel\fR. If |
---|
522 | \fIbytesToWrite\fR is negative, \fBTcl_WriteChars\fR expects \fIcharBuf\fR |
---|
523 | to be null-terminated and it outputs everything up to the null. |
---|
524 | .PP |
---|
525 | Data queued for output may not appear on the output device immediately, due |
---|
526 | to internal buffering. If the data should appear immediately, call |
---|
527 | \fBTcl_Flush\fR after the call to \fBTcl_WriteChars\fR, or set the |
---|
528 | \fB\-buffering\fR option on the channel to \fBnone\fR. If you wish the data |
---|
529 | to appear as soon as a complete line is accepted for output, set the |
---|
530 | \fB\-buffering\fR option on the channel to \fBline\fR mode. |
---|
531 | .PP |
---|
532 | The return value of \fBTcl_WriteChars\fR is a count of how many bytes were |
---|
533 | accepted for output to the channel. This is either greater than zero to |
---|
534 | indicate success or \-1 to indicate that an error occurred. If an error |
---|
535 | occurs, \fBTcl_WriteChars\fR records a POSIX error code that may be |
---|
536 | retrieved with \fBTcl_GetErrno\fR. |
---|
537 | .PP |
---|
538 | Newline characters in the output data are translated to platform-specific |
---|
539 | end-of-line sequences according to the \fB\-translation\fR option for the |
---|
540 | channel. This is done even if the channel has no encoding. |
---|
541 | .PP |
---|
542 | \fBTcl_WriteObj\fR is similar to \fBTcl_WriteChars\fR except it |
---|
543 | accepts a Tcl object whose contents will be output to the channel. The |
---|
544 | UTF-8 characters in \fIwriteObjPtr\fR's string representation are converted |
---|
545 | to the channel's encoding and queued for output to \fIchannel\fR. |
---|
546 | As a performance optimization, when writing to a channel with the encoding |
---|
547 | \fBbinary\fR, UTF-8 characters are not converted as they are written. |
---|
548 | Instead, the bytes in \fIwriteObjPtr\fR's internal representation as a |
---|
549 | byte-array object are written to the channel. The byte-array representation |
---|
550 | of the object will be constructed if it is needed. In this way, |
---|
551 | byte-oriented data can be read from a channel, manipulated by calling |
---|
552 | \fBTcl_GetByteArrayFromObj\fR and related functions, and then written to a |
---|
553 | channel without the expense of ever converting to or from UTF-8. |
---|
554 | .PP |
---|
555 | \fBTcl_Write\fR is similar to \fBTcl_WriteChars\fR except that it does not do |
---|
556 | encoding conversions, regardless of the channel's encoding. It is |
---|
557 | deprecated and exists for backwards compatibility with non-internationalized |
---|
558 | Tcl extensions. It accepts \fIbytesToWrite\fR bytes of data at |
---|
559 | \fIbyteBuf\fR and queues them for output to \fIchannel\fR. If |
---|
560 | \fIbytesToWrite\fR is negative, \fBTcl_Write\fR expects \fIbyteBuf\fR to be |
---|
561 | null-terminated and it outputs everything up to the null. |
---|
562 | .PP |
---|
563 | \fBTcl_WriteRaw\fR is the same as \fBTcl_Write\fR but does not |
---|
564 | compensate for stacking. While \fBTcl_Write\fR (and the other |
---|
565 | functions in the API) always feed their input to the topmost channel |
---|
566 | in the stack the supplied channel is part of, \fBTcl_WriteRaw\fR does |
---|
567 | not. Thus this function is \fBonly\fR usable for transformational |
---|
568 | channel drivers, i.e. drivers used in the middle of a stack of |
---|
569 | channels, to move data from the transformation into the channel below |
---|
570 | it. |
---|
571 | |
---|
572 | .SH TCL_FLUSH |
---|
573 | .PP |
---|
574 | \fBTcl_Flush\fR causes all of the buffered output data for \fIchannel\fR |
---|
575 | to be written to its underlying file or device as soon as possible. |
---|
576 | If the channel is in blocking mode, the call does not return until |
---|
577 | all the buffered data has been sent to the channel or some error occurred. |
---|
578 | The call returns immediately if the channel is nonblocking; it starts |
---|
579 | a background flush that will write the buffered data to the channel |
---|
580 | eventually, as fast as the channel is able to absorb it. |
---|
581 | .PP |
---|
582 | The return value is normally \fBTCL_OK\fR. |
---|
583 | If an error occurs, \fBTcl_Flush\fR returns \fBTCL_ERROR\fR and |
---|
584 | records a POSIX error code that can be retrieved with \fBTcl_GetErrno\fR. |
---|
585 | |
---|
586 | .SH TCL_SEEK |
---|
587 | .PP |
---|
588 | \fBTcl_Seek\fR moves the access point in \fIchannel\fR where subsequent |
---|
589 | data will be read or written. Buffered output is flushed to the channel and |
---|
590 | buffered input is discarded, prior to the seek operation. |
---|
591 | .PP |
---|
592 | \fBTcl_Seek\fR normally returns the new access point. |
---|
593 | If an error occurs, \fBTcl_Seek\fR returns \-1 and records a POSIX error |
---|
594 | code that can be retrieved with \fBTcl_GetErrno\fR. |
---|
595 | After an error, the access point may or may not have been moved. |
---|
596 | |
---|
597 | .SH TCL_TELL |
---|
598 | .PP |
---|
599 | \fBTcl_Tell\fR returns the current access point for a channel. The returned |
---|
600 | value is \-1 if the channel does not support seeking. |
---|
601 | |
---|
602 | .SH TCL_TRUNCATECHANNEL |
---|
603 | .PP |
---|
604 | .VS 8.5 |
---|
605 | \fBTcl_TruncateChannel\fR truncates the file underlying \fIchannel\fR |
---|
606 | to a given \fIlength\fR of bytes. It returns \fBTCL_OK\fR if the |
---|
607 | operation succeeded, and \fBTCL_ERROR\fR otherwise. |
---|
608 | .VE 8.5 |
---|
609 | |
---|
610 | .SH TCL_GETCHANNELOPTION |
---|
611 | .PP |
---|
612 | \fBTcl_GetChannelOption\fR retrieves, in \fIoptionValue\fR, the value of one of |
---|
613 | the options currently in effect for a channel, or a list of all options and |
---|
614 | their values. The \fIchannel\fR argument identifies the channel for which |
---|
615 | to query an option or retrieve all options and their values. |
---|
616 | If \fIoptionName\fR is not NULL, it is the name of the |
---|
617 | option to query; the option's value is copied to the Tcl dynamic string |
---|
618 | denoted by \fIoptionValue\fR. If |
---|
619 | \fIoptionName\fR is NULL, the function stores an alternating list of option |
---|
620 | names and their values in \fIoptionValue\fR, using a series of calls to |
---|
621 | \fBTcl_DStringAppendElement\fR. The various preexisting options and |
---|
622 | their possible values are described in the manual entry for the Tcl |
---|
623 | \fBfconfigure\fR command. Other options can be added by each channel type. |
---|
624 | These channel type specific options are described in the manual entry for |
---|
625 | the Tcl command that creates a channel of that type; for example, the |
---|
626 | additional options for TCP based channels are described in the manual entry |
---|
627 | for the Tcl \fBsocket\fR command. |
---|
628 | The procedure normally returns \fBTCL_OK\fR. If an error occurs, it returns |
---|
629 | \fBTCL_ERROR\fR and calls \fBTcl_SetErrno\fR to store an appropriate POSIX |
---|
630 | error code. |
---|
631 | |
---|
632 | .SH TCL_SETCHANNELOPTION |
---|
633 | .PP |
---|
634 | \fBTcl_SetChannelOption\fR sets a new value \fInewValue\fR |
---|
635 | for an option \fIoptionName\fR on \fIchannel\fR. |
---|
636 | The procedure normally returns \fBTCL_OK\fR. If an error occurs, |
---|
637 | it returns \fBTCL_ERROR\fR; in addition, if \fIinterp\fR is non-NULL, |
---|
638 | \fBTcl_SetChannelOption\fR leaves an error message in the interpreter's result. |
---|
639 | |
---|
640 | .SH TCL_EOF |
---|
641 | .PP |
---|
642 | \fBTcl_Eof\fR returns a nonzero value if \fIchannel\fR encountered |
---|
643 | an end of file during the last input operation. |
---|
644 | |
---|
645 | .SH TCL_INPUTBLOCKED |
---|
646 | .PP |
---|
647 | \fBTcl_InputBlocked\fR returns a nonzero value if \fIchannel\fR is in |
---|
648 | nonblocking mode and the last input operation returned less data than |
---|
649 | requested because there was insufficient data available. |
---|
650 | The call always returns zero if the channel is in blocking mode. |
---|
651 | |
---|
652 | .SH TCL_INPUTBUFFERED |
---|
653 | .PP |
---|
654 | \fBTcl_InputBuffered\fR returns the number of bytes of input currently |
---|
655 | buffered in the internal buffers for a channel. If the channel is not open |
---|
656 | for reading, this function always returns zero. |
---|
657 | |
---|
658 | .SH TCL_OUTPUTBUFFERED |
---|
659 | \fBTcl_OutputBuffered\fR returns the number of bytes of output |
---|
660 | currently buffered in the internal buffers for a channel. If the |
---|
661 | channel is not open for writing, this function always returns zero. |
---|
662 | |
---|
663 | .SH "PLATFORM ISSUES" |
---|
664 | .PP |
---|
665 | The handles returned from \fBTcl_GetChannelHandle\fR depend on the |
---|
666 | platform and the channel type. On Unix platforms, the handle is |
---|
667 | always a Unix file descriptor as returned from the \fBopen\fR system |
---|
668 | call. On Windows platforms, the handle is a file \fBHANDLE\fR when |
---|
669 | the channel was created with \fBTcl_OpenFileChannel\fR, |
---|
670 | \fBTcl_OpenCommandChannel\fR, or \fBTcl_MakeFileChannel\fR. Other |
---|
671 | channel types may return a different type of handle on Windows |
---|
672 | platforms. |
---|
673 | |
---|
674 | .SH "SEE ALSO" |
---|
675 | DString(3), fconfigure(n), filename(n), fopen(3), Tcl_CreateChannel(3) |
---|
676 | |
---|
677 | .SH KEYWORDS |
---|
678 | access point, blocking, buffered I/O, channel, channel driver, end of file, |
---|
679 | flush, input, nonblocking, output, read, seek, write |
---|