[25] | 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 |
---|