diff options
Diffstat (limited to 'doc/OpenFileChnl.3')
| -rw-r--r-- | doc/OpenFileChnl.3 | 499 |
1 files changed, 0 insertions, 499 deletions
diff --git a/doc/OpenFileChnl.3 b/doc/OpenFileChnl.3 deleted file mode 100644 index c0d121c..0000000 --- a/doc/OpenFileChnl.3 +++ /dev/null @@ -1,499 +0,0 @@ -'\" -'\" Copyright (c) 1996-1997 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -'\" RCS: @(#) $Id: OpenFileChnl.3,v 1.2 1998/09/14 18:39:49 stanton Exp $ -.so man.macros -.TH Tcl_OpenFileChannel 3 8.0 Tcl "Tcl Library Procedures" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -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 -.SH SYNOPSIS -.nf -\fB#include <tcl.h>\fR -.sp -typedef ... Tcl_Channel; -.sp -Tcl_Channel -\fBTcl_OpenFileChannel\fR(\fIinterp, fileName, mode, permissions\fR) -.sp -Tcl_Channel -\fBTcl_OpenCommandChannel\fR(\fIinterp, argc, argv, flags\fR) -.VS -.sp -Tcl_Channel -\fBTcl_MakeFileChannel\fR(\fIhandle, readOrWrite\fR) -.VE -.sp -Tcl_Channel -\fBTcl_GetChannel\fR(\fIinterp, channelName, modePtr\fR) -.sp -void -\fBTcl_RegisterChannel\fR(\fIinterp, channel\fR) -.sp -int -\fBTcl_UnregisterChannel\fR(\fIinterp, channel\fR) -.sp -int -\fBTcl_Close\fR(\fIinterp, channel\fR) -.sp -int -\fBTcl_Read\fR(\fIchannel, buf, toRead\fR) -.sp -int -\fBTcl_Gets\fR(\fIchannel, lineRead\fR) -.sp -int -\fBTcl_GetsObj\fR(\fIchannel, lineObjPtr\fR) -.sp -int -\fBTcl_Write\fR(\fIchannel, buf, toWrite\fR) -.sp -int -\fBTcl_Flush\fR(\fIchannel\fR) -.sp -int -\fBTcl_Seek\fR(\fIchannel, offset, seekMode\fR) -.sp -int -\fBTcl_Tell\fR(\fIchannel\fR) -.sp -int -\fBTcl_GetChannelOption\fR(\fIinterp, channel, optionName, optionValue\fR) -.sp -int -\fBTcl_SetChannelOption\fR(\fIinterp, channel, optionName, newValue\fR) -.sp -int -\fBTcl_Eof\fR(\fIchannel\fR) -.sp -int -\fBTcl_InputBlocked\fR(\fIchannel\fR) -.sp -int -\fBTcl_InputBuffered\fR(\fIchannel\fR) -.sp -.SH ARGUMENTS -.AS Tcl_ChannelType newClientProcPtr in -.AP Tcl_Interp *interp in -Used for error reporting and to look up a channel registered in it. -.AP char *fileName in -The name of a local or network file. -.AP char *mode in -Specifies how the file is to be accessed. May have any of the -values allowed for the \fImode\fR argument to the Tcl -\fBopen\fR command. -For \fBTcl_OpenCommandChannel\fR, may be NULL. -.AP int permissions in -POSIX-style permission flags such as 0644. -If a new file is created, these permissions will be set on the -created file. -.AP int argc in -The number of elements in \fIargv\fR. -.AP char **argv in -Arguments for constructing a command pipeline. -These values have the same meaning as the non-switch arguments -to the Tcl \fBexec\fR command. -.AP int flags in -Specifies the disposition of the stdio handles in pipeline: OR-ed -combination of \fBTCL_STDIN\fR, \fBTCL_STDOUT\fR, \fBTCL_STDERR\fR, -and \fBTCL_ENFORCE_MODE\fR. If \fBTCL_STDIN\fR is set, stdin for -the first child in the pipe is the pipe channel, otherwise it is the same -as the standard input of the invoking process; likewise for -\fBTCL_STDOUT\fR and \fBTCL_STDERR\fR. If \fBTCL_ENFORCE_MODE\fR is not set, -then the pipe can redirect stdio handles to override the stdio handles for -which \fBTCL_STDIN\fR, \fBTCL_STDOUT\fR and \fBTCL_STDERR\fR have been set. -If it is set, then such redirections cause an error. -.VS -.AP ClientData handle in -Operating system specific handle for I/O to a file. For Unix this is a -file descriptor, for Windows it is a HANDLE. -.AP int readOrWrite in -OR-ed combination of \fBTCL_READABLE\fR and \fBTCL_WRITABLE\fR to indicate -what operations are valid on \fIhandle\fR. -.VE -.AP int *modePtr out -Points at an integer variable that will receive an OR-ed combination of -\fBTCL_READABLE\fR and \fBTCL_WRITABLE\fR denoting whether the channel is -open for reading and writing. -.AP Tcl_Channel channel in -A Tcl channel for input or output. Must have been the return value -from a procedure such as \fBTcl_OpenFileChannel\fR. -.AP char *buf in -An array of bytes in which to store channel input, or from which -to read channel output. -.AP int len in -The length of the input or output. -.AP int atEnd in -If nonzero, store the input at the end of the input queue, otherwise store -it at the head of the input queue. -.AP int toRead in -The number of bytes to read from the channel. -.AP Tcl_DString *lineRead in -A pointer to a Tcl dynamic string in which to store the line read from the -channel. Must have been initialized by the caller. The line read -will be appended to any data already in the dynamic string. -.AP Tcl_Obj *linePtrObj in -A pointer to a Tcl object in which to store the line read from the -channel. The line read will be appended to the current value of the -object. -.AP int toWrite in -The number of bytes to read from \fIbuf\fR and output to the channel. -.AP int offset in -How far to move the access point in the channel at which the next input or -output operation will be applied, measured in bytes from the position -given by \fIseekMode\fR. May be either positive or negative. -.AP int seekMode in -Relative to which point to seek; used with \fIoffset\fR to calculate the new -access point for the channel. Legal values are \fBSEEK_SET\fR, -\fBSEEK_CUR\fR, and \fBSEEK_END\fR. -.AP char *optionName in -The name of an option applicable to this channel, such as \fB\-blocking\fR. -May have any of the values accepted by the \fBfconfigure\fR command. -.AP Tcl_DString *optionValue in -Where to store the value of an option or a list of all options and their -values. Must have been initialized by the caller. -.AP char *newValue in -New value for the option given by \fIoptionName\fR. -.BE - -.SH DESCRIPTION -.PP -The Tcl channel mechanism provides a device-independent and -platform-independent mechanism for performing buffered input -and output operations on a variety of file, socket, and device -types. -The channel mechanism is extensible to new channel types, by -providing a low level channel driver for the new type; the channel driver -interface is described in the manual entry for \fBTcl_CreateChannel\fR. The -channel mechanism provides a buffering scheme modelled after -Unix's standard I/O, and it also allows for nonblocking I/O on -channels. -.PP -The procedures described in this manual entry comprise the C APIs of the -generic layer of the channel architecture. For a description of the channel -driver architecture and how to implement channel drivers for new types of -channels, see the manual entry for \fBTcl_CreateChannel\fR. - -.SH TCL_OPENFILECHANNEL -.PP -\fBTcl_OpenFileChannel\fR opens a file specified by \fIfileName\fR and -returns a channel handle that can be used to perform input and output on -the file. This API is modelled after the \fBfopen\fR procedure of -the Unix standard I/O library. -The syntax and meaning of all arguments is similar to those -given in the Tcl \fBopen\fR command when opening a file. -If an error occurs while opening the channel, \fBTcl_OpenFileChannel\fR -returns NULL and records a POSIX error code that can be -retrieved with \fBTcl_GetErrno\fR. -In addition, if \fIinterp\fR is non-NULL, \fBTcl_OpenFileChannel\fR -leaves an error message in \fIinterp->result\fR after any error. -.PP -The newly created channel is not registered in the supplied interpreter; to -register it, use \fBTcl_RegisterChannel\fR, described below. -If one of the standard channels, \fBstdin, stdout\fR or \fBstderr\fR was -previously closed, the act of creating the new channel also assigns it as a -replacement for the standard channel. - -.SH TCL_OPENCOMMANDCHANNEL -.PP -\fBTcl_OpenCommandChannel\fR provides a C-level interface to the -functions of the \fBexec\fR and \fBopen\fR commands. -It creates a sequence of subprocesses specified -by the \fIargv\fR and \fIargc\fR arguments and returns a channel that can -be used to communicate with these subprocesses. -The \fIflags\fR argument indicates what sort of communication will -exist with the command pipeline. -.PP -If the \fBTCL_STDIN\fR flag is set then the standard input for the -first subprocess will be tied to the channel: writing to the channel -will provide input to the subprocess. If \fBTCL_STDIN\fR is not set, -then standard input for the first subprocess will be the same as this -application's standard input. If \fBTCL_STDOUT\fR is set then -standard output from the last subprocess can be read from the channel; -otherwise it goes to this application's standard output. If -\fBTCL_STDERR\fR is set, standard error output for all subprocesses is -returned to the channel and results in an error when the channel is -closed; otherwise it goes to this application's standard error. If -\fBTCL_ENFORCE_MODE\fR is not set, then \fIargc\fR and \fIargv\fR can -redirect the stdio handles to override \fBTCL_STDIN\fR, -\fBTCL_STDOUT\fR, and \fBTCL_STDERR\fR; if it is set, then it is an -error for argc and argv to override stdio channels for which -\fBTCL_STDIN\fR, \fBTCL_STDOUT\fR, and \fBTCL_STDERR\fR have been set. -.PP -If an error occurs while opening the channel, \fBTcl_OpenCommandChannel\fR -returns NULL and records a POSIX error code that can be retrieved with -\fBTcl_GetErrno\fR. -In addition, \fBTcl_OpenCommandChannel\fR leaves an error message in -\fIinterp->result\fR if \fIinterp\fR is not NULL. -.PP -The newly created channel is not registered in the supplied interpreter; to -register it, use \fBTcl_RegisterChannel\fR, described below. -If one of the standard channels, \fBstdin, stdout\fR or \fBstderr\fR was -previously closed, the act of creating the new channel also assigns it as a -replacement for the standard channel. - -.SH TCL_MAKEFILECHANNEL -.PP -\fBTcl_MakeFileChannel\fR makes a \fBTcl_Channel\fR from an existing, -platform-specific, file handle. -The newly created channel is not registered in the supplied interpreter; to -register it, use \fBTcl_RegisterChannel\fR, described below. -If one of the standard channels, \fBstdin, stdout\fR or \fBstderr\fR was -previously closed, the act of creating the new channel also assigns it as a -replacement for the standard channel. - -.SH TCL_GETCHANNEL -.PP -\fBTcl_GetChannel\fR returns a channel given the \fIchannelName\fR used to -create it with \fBTcl_CreateChannel\fR and a pointer to a Tcl interpreter in -\fIinterp\fR. If a channel by that name is not registered in that interpreter, -the procedure returns NULL. If the \fImode\fR argument is not NULL, it -points at an integer variable that will receive an OR-ed combination of -\fBTCL_READABLE\fR and \fBTCL_WRITABLE\fR describing whether the channel is -open for reading and writing. - -.SH TCL_REGISTERCHANNEL -.PP -\fBTcl_RegisterChannel\fR adds a channel to the set of channels accessible -in \fIinterp\fR. After this call, Tcl programs executing in that -interpreter can refer to the channel in input or output operations using -the name given in the call to \fBTcl_CreateChannel\fR. After this call, -the channel becomes the property of the interpreter, and the caller should -not call \fBTcl_Close\fR for the channel; the channel will be closed -automatically when it is unregistered from the interpreter. -.PP -Code executing outside of any Tcl interpreter can call -\fBTcl_RegisterChannel\fR with \fIinterp\fR as NULL, to indicate that it -wishes to hold a reference to this channel. Subsequently, the channel can -be registered in a Tcl interpreter and it will only be closed when the -matching number of calls to \fBTcl_UnregisterChannel\fR have been made. -This allows code executing outside of any interpreter to safely hold a -reference to a channel that is also registered in a Tcl interpreter. - -.SH TCL_UNREGISTERCHANNEL -.PP -\fBTcl_UnregisterChannel\fR removes a channel from the set of channels -accessible in \fIinterp\fR. After this call, Tcl programs will no longer be -able to use the channel's name to refer to the channel in that interpreter. -If this operation removed the last registration of the channel in any -interpreter, the channel is also closed and destroyed. -.PP -Code not associated with a Tcl interpreter can call -\fBTcl_UnregisterChannel\fR with \fIinterp\fR as NULL, to indicate to Tcl -that it no longer holds a reference to that channel. If this is the last -reference to the channel, it will now be closed. - -.SH TCL_CLOSE -.PP -\fBTcl_Close\fR destroys the channel \fIchannel\fR, which must denote a -currently open channel. The channel should not be registered in any -interpreter when \fBTcl_Close\fR is called. Buffered output is flushed to -the channel's output device prior to destroying the channel, and any -buffered input is discarded. If this is a blocking channel, the call does -not return until all buffered data is successfully sent to the channel's -output device. If this is a nonblocking channel and there is buffered -output that cannot be written without blocking, the call returns -immediately; output is flushed in the background and the channel will be -closed once all of the buffered data has been output. In this case errors -during flushing are not reported. -.PP -If the channel was closed successfully, \fBTcl_Close\fR returns \fBTCL_OK\fR. -If an error occurs, \fBTcl_Close\fR returns \fBTCL_ERROR\fR and records a -POSIX error code that can be retrieved with \fBTcl_GetErrno\fR. -If the channel is being closed synchronously and an error occurs during -closing of the channel and \fIinterp\fR is not NULL, an error message is -left in \fIinterp->result\fR. -.PP -Note: it is not safe to call \fBTcl_Close\fR on a channel that has been -registered using \fBTcl_RegisterChannel\fR; see the documentation for -\fBTcl_RegisterChannel\fR, above, for details. If the channel has ever been -given as the \fBchan\fR argument in a call to \fBTcl_RegisterChannel\fR, -you should instead use \fBTcl_UnregisterChannel\fR, which will internally -call \fBTcl_Close\fR when all calls to \fBTcl_RegisterChannel\fR have been -matched by corresponding calls to \fBTcl_UnregisterChannel\fR. - -.SH TCL_READ -.PP -\fBTcl_Read\fR consumes up to \fItoRead\fR bytes of data from -\fIchannel\fR and stores it at \fIbuf\fR. -The return value of \fBTcl_Read\fR is the number of characters written -at \fIbuf\fR. -The buffer produced by \fBTcl_Read\fR is not NULL terminated. Its contents -are valid from the zeroth position up to and excluding the position -indicated by the return value. -If an error occurs, the return value is -1 and \fBTcl_Read\fR records -a POSIX error code that can be retrieved with \fBTcl_GetErrno\fR. -.PP -The return value may be smaller than the value of \fItoRead\fR, indicating -that less data than requested was available, also called a \fIshort -read\fR. -In blocking mode, this can only happen on an end-of-file. -In nonblocking mode, a short read can also occur if there is not -enough input currently available: \fBTcl_Read\fR returns a short -count rather than waiting for more data. -.PP -If the channel is in blocking mode, a return value of zero indicates an end -of file condition. If the channel is in nonblocking mode, a return value of -zero indicates either that no input is currently available or an end of -file condition. Use \fBTcl_Eof\fR and \fBTcl_InputBlocked\fR -to tell which of these conditions actually occurred. -.PP -\fBTcl_Read\fR translates platform-specific end-of-line representations -into the canonical \fB\en\fR internal representation according to the -current end-of-line recognition mode. End-of-line recognition and the -various platform-specific modes are described in the manual entry for the -Tcl \fBfconfigure\fR command. - -.SH TCL_GETS AND TCL_GETSOBJ -.PP -\fBTcl_Gets\fR reads a line of input from a channel and appends all of -the characters of the line except for the terminating end-of-line character(s) -to the dynamic string given by \fIdsPtr\fR. -The end-of-line character(s) are read and discarded. -.PP -If a line was successfully read, the return value is greater than or -equal to zero, and it indicates the number of characters stored -in the dynamic string. -If an error occurs, \fBTcl_Gets\fR returns -1 and records a POSIX error -code that can be retrieved with \fBTcl_GetErrno\fR. -\fBTcl_Gets\fR also returns -1 if the end of the file is reached; -the \fBTcl_Eof\fR procedure can be used to distinguish an error -from an end-of-file condition. -.PP -If the channel is in nonblocking mode, the return value can also -be -1 if no data was available or the data that was available -did not contain an end-of-line character. -When -1 is returned, the \fBTcl_InputBlocked\fR procedure may be -invoked to determine if the channel is blocked because of input -unavailability. -.PP -\fBTcl_GetsObj\fR is the same as \fBTcl_Gets\fR except the resulting -characters are appended to a Tcl object \fBlineObjPtr\fR rather than a -dynamic string. -.SH TCL_WRITE -.PP -\fBTcl_Write\fR accepts \fItoWrite\fR bytes of data at \fIbuf\fR for output -on \fIchannel\fR. This data may not appear on the output device -immediately. If the data should appear immediately, call \fBTcl_Flush\fR -after the call to \fBTcl_Write\fR, or set the \fB-buffering\fR option on -the channel to \fBnone\fR. If you wish the data to appear as soon as an end -of line is accepted for output, set the \fB\-buffering\fR option on the -channel to \fBline\fR mode. -.PP -The \fItoWrite\fR argument specifies how many bytes of data are provided in -the \fIbuf\fR argument. If it is negative, \fBTcl_Write\fR expects the data -to be NULL terminated and it outputs everything up to the NULL. -.PP -The return value of \fBTcl_Write\fR is a count of how many -characters were accepted for output to the channel. This is either equal to -\fItoWrite\fR or -1 to indicate that an error occurred. -If an error occurs, \fBTcl_Write\fR also records a POSIX error code -that may be retrieved with \fBTcl_GetErrno\fR. -.PP -Newline characters in the output data are translated to platform-specific -end-of-line sequences according to the \fB\-translation\fR option for -the channel. - -.SH TCL_FLUSH -.PP -\fBTcl_Flush\fR causes all of the buffered output data for \fIchannel\fR -to be written to its underlying file or device as soon as possible. -If the channel is in blocking mode, the call does not return until -all the buffered data has been sent to the channel or some error occurred. -The call returns immediately if the channel is nonblocking; it starts -a background flush that will write the buffered data to the channel -eventually, as fast as the channel is able to absorb it. -.PP -The return value is normally \fBTCL_OK\fR. -If an error occurs, \fBTcl_Flush\fR returns \fBTCL_ERROR\fR and -records a POSIX error code that can be retrieved with \fBTcl_GetErrno\fR. - -.SH TCL_SEEK -.PP -\fBTcl_Seek\fR moves the access point in \fIchannel\fR where subsequent -data will be read or written. Buffered output is flushed to the channel and -buffered input is discarded, prior to the seek operation. -.PP -\fBTcl_Seek\fR normally returns the new access point. -If an error occurs, \fBTcl_Seek\fR returns -1 and records a POSIX error -code that can be retrieved with \fBTcl_GetErrno\fR. -After an error, the access point may or may not have been moved. - -.SH TCL_TELL -.PP -\fBTcl_Tell\fR returns the current access point for a channel. The returned -value is -1 if the channel does not support seeking. - -.SH TCL_GETCHANNELOPTION -.PP -\fBTcl_GetChannelOption\fR retrieves, in \fIdsPtr\fR, the value of one of -the options currently in effect for a channel, or a list of all options and -their values. The \fIchannel\fR argument identifies the channel for which -to query an option or retrieve all options and their values. -If \fIoptionName\fR is not NULL, it is the name of the -option to query; the option's value is copied to the Tcl dynamic string -denoted by \fIoptionValue\fR. If -\fIoptionName\fR is NULL, the function stores an alternating list of option -names and their values in \fIoptionValue\fR, using a series of calls to -\fBTcl_DStringAppendElement\fR. The various preexisting options and -their possible values are described in the manual entry for the Tcl -\fBfconfigure\fR command. Other options can be added by each channel type. -These channel type specific options are described in the manual entry for -the Tcl command that creates a channel of that type; for example, the -additional options for TCP based channels are described in the manual entry -for the Tcl \fBsocket\fR command. -The procedure normally returns \fBTCL_OK\fR. If an error occurs, it returns -\fBTCL_ERROR\fR and calls \fBTcl_SetErrno\fR to store an appropriate POSIX -error code. - -.SH TCL_SETCHANNELOPTION -.PP -\fBTcl_SetChannelOption\fR sets a new value for an option on \fIchannel\fR. -\fIOptionName\fR is the option to set and \fInewValue\fR is the value to -set. -The procedure normally returns \fBTCL_OK\fR. If an error occurs, -it returns \fBTCL_ERROR\fR; in addition, if \fIinterp\fR is non-NULL, -\fBTcl_SetChannelOption\fR leaves an error message in \fIinterp->result\fR. - -.SH TCL_EOF -.PP -\fBTcl_Eof\fR returns a nonzero value if \fIchannel\fR encountered -an end of file during the last input operation. - -.SH TCL_INPUTBLOCKED -.PP -\fBTcl_InputBlocked\fR returns a nonzero value if \fIchannel\fR is in -nonblocking mode and the last input operation returned less data than -requested because there was insufficient data available. -The call always returns zero if the channel is in blocking mode. - -.SH TCL_INPUTBUFFERED -.PP -\fBTcl_InputBuffered\fR returns the number of bytes of input currently -buffered in the internal buffers for a channel. If the channel is not open -for reading, this function always returns zero. - -.VS -.SH "PLATFORM ISSUES" -.PP -The handles returned from \fBTcl_GetChannelHandle\fR depend on the -platform and the channel type. On Unix platforms, the handle is -always a Unix file descriptor as returned from the \fBopen\fR system -call. On Windows platforms, the handle is a file \fBHANDLE\fR when -the channel was created with \fBTcl_OpenFileChannel\fR, -\fBTcl_OpenCommandChannel\fR, or \fBTcl_MakeFileChannel\fR. Other -channel types may return a different type of handle on Windows -platforms. On the Macintosh platform, the handle is a file reference -number as returned from \fBHOpenDF\fR. -.VE - -.SH "SEE ALSO" -DString(3), fconfigure(n), filename(n), fopen(2), Tcl_CreateChannel(3) - -.SH KEYWORDS -access point, blocking, buffered I/O, channel, channel driver, end of file, -flush, input, nonblocking, output, read, seek, write |