diff options
Diffstat (limited to 'contrib/tcl/doc/OpenFileChnl.3')
-rw-r--r-- | contrib/tcl/doc/OpenFileChnl.3 | 441 |
1 files changed, 441 insertions, 0 deletions
diff --git a/contrib/tcl/doc/OpenFileChnl.3 b/contrib/tcl/doc/OpenFileChnl.3 new file mode 100644 index 0000000..c17cc64 --- /dev/null +++ b/contrib/tcl/doc/OpenFileChnl.3 @@ -0,0 +1,441 @@ +'\" +'\" Copyright (c) 1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) OpenFileChnl.3 1.27 96/03/22 14:55:07 +.so man.macros +.TH Tcl_OpenFileChannel 3 7.5 Tcl "Tcl Library Procedures" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +Tcl_OpenFileChannel, Tcl_OpenCommandChannel, Tcl_Close, Tcl_Read, Tcl_Gets, Tcl_Write, Tcl_Flush, Tcl_Seek, Tcl_Tell, Tcl_Eof, Tcl_InputBlocked, 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) +.sp +Tcl_Channel +\fBTcl_MakeFileChannel\fR(\fIinOsFile, outOsFile, readOrWrite\fR) +.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_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(\fIchannel, 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. +.AP ClientData inOsFile in +Operating system specific handle for input from a file. For Unix this is a +file descriptor, for Windows it is a HANDLE, etc. +.AP ClientData outOsFile in +Operating system specific handle for output to a file. +.AP int readOrWrite in +OR-ed combination of \fBTCL_READABLE\fR and \fBTCL_WRITABLE\fR to indicate +which of \fIinOsFile\fR and \fIoutOsFile\fR contains a valid value. +.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 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. +.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. + +.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. + +.SH TCL_MAKEFILECHANNEL +.PP +\fBTcl_MakeFileChannel\fR makes a \fBTcl_Channel\fR from an existing, +platform-specific, file handle. + +.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. +The caller should not call \fBTcl_Close\fR for the channel; the +channel will be closed automatically when it is unregistered from +the interpreter. +Furthermore, it is not generally safe to reference the channel +anymore, since it could be deleted at any time by a \fBclose\fR +command in the 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. + +.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; see the manual entry for \fBTcl_CreateChannel\fR +for a description of \fBTcl_RegisterChannel\fR and \fBTcl_UnregisterChannel\fR. +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 in an interpreter using \fBTcl_RegisterChannel\fR; +see the documentation for \fBTcl_RegisterChannel\fR for details. + +.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 +.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. + +.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. + +.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 |