From 9124316ee7cc50a30161a176ef51b0432a068a78 Mon Sep 17 00:00:00 2001 From: Jarkko Hietaniemi Date: Wed, 21 Nov 2001 00:37:00 +0000 Subject: [PATCH] Try to clarify which I/O call operates on bytes, which on characters, which on either. p4raw-id: //depot/perl@13146 --- pod/perlfunc.pod | 206 ++++++++++++++++++++++++++++++++++++------------------- 1 file changed, 135 insertions(+), 71 deletions(-) diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod index 3feb50d..be2ab64 100644 --- a/pod/perlfunc.pod +++ b/pod/perlfunc.pod @@ -339,7 +339,7 @@ file is examined for odd characters such as strange control codes or characters with the high bit set. If too many strange characters (>30%) are found, it's a C<-B> file, otherwise it's a C<-T> file. Also, any file containing null in the first block is considered a binary file. If C<-T> -or C<-B> is used on a filehandle, the current stdio buffer is examined +or C<-B> is used on a filehandle, the current IO buffer is examined rather than the first block. Both C<-T> and C<-B> return true on a null file, or a file at EOF when testing a filehandle. Because you have to read a file to do the C<-T> test, on most occasions you want to use a C<-f> @@ -712,10 +712,10 @@ omitted, does a C to C<$_>. =item close -Closes the file or pipe associated with the file handle, returning true -only if stdio successfully flushes buffers and closes the system file -descriptor. Closes the currently selected filehandle if the argument -is omitted. +Closes the file or pipe associated with the file handle, returning +true only if IO buffers are successfully flushed and closes the system +file descriptor. Closes the currently selected filehandle if the +argument is omitted. You don't have to close FILEHANDLE if you are immediately going to do another C on it, because C will close it for you. (See @@ -2735,7 +2735,12 @@ and opening C<< '>-' >> opens STDOUT. You may use the three-argument form of open to specify I that affect how the input and output -are processed: see L and L. +are processed: see L and L. For example + + open(FH, "<:utf8", "file") + +will open the UTF-8 encoded file containing Unicode characters, +see L. Open returns nonzero upon success, the undefined value otherwise. If the C involved a pipe, the return value happens to be the pid of @@ -2824,7 +2829,7 @@ duped and opened. You may use C<&> after C<< > >>, C<<< >> >>>, C<< < >>, C<< +> >>, C<<< +>> >>>, and C<< +< >>. The mode you specify should match the mode of the original filehandle. (Duping a filehandle does not take into account any existing contents of -stdio buffers.) If you use the 3 arg form then you can pass either a number, +IO buffers.) If you use the 3 arg form then you can pass either a number, the name of a filehandle or the normal "reference to a glob". Here is a script that saves, redirects, and restores STDOUT and @@ -3459,7 +3464,7 @@ and classes. See L for other scoping issues. Opens a pair of connected pipes like the corresponding system call. Note that if you set up a loop of piped processes, deadlock can occur unless you are very careful. In addition, note that Perl's pipes use -stdio buffering, so you may need to set C<$|> to flush your WRITEHANDLE +IO buffering, so you may need to set C<$|> to flush your WRITEHANDLE after each command, depending on the application. See L, L, and L @@ -3615,14 +3620,21 @@ with the wrong number of RANDBITS.) =item read FILEHANDLE,SCALAR,LENGTH -Attempts to read LENGTH bytes of data into variable SCALAR from the -specified FILEHANDLE. Returns the number of bytes actually read, C<0> -at end of file, or undef if there was an error. SCALAR will be grown -or shrunk to the length actually read. If SCALAR needs growing, the -new bytes will be zero bytes. An OFFSET may be specified to place -the read data into some other place in SCALAR than the beginning. -The call is actually implemented in terms of stdio's fread(3) call. -To get a true read(2) system call, see C. +Attempts to read LENGTH I of data into variable SCALAR +from the specified FILEHANDLE. Returns the number of characters +actually read, C<0> at end of file, or undef if there was an error. +SCALAR will be grown or shrunk to the length actually read. If SCALAR +needs growing, the new bytes will be zero bytes. An OFFSET may be +specified to place the read data into some other place in SCALAR than +the beginning. The call is actually implemented in terms of either +Perl's or system's fread() call. To get a true read(2) system call, +see C. + +Note the I: depending on the status of the filehandle, +either (8-bit) bytes or characters are read. By default all +filehandles operate on bytes, but for example if the filehandle has +been opened with the C<:utf8> discipline (see L, and the C +pragma, L), the I/O will operate on characters, not bytes. =item readdir DIRHANDLE @@ -3681,14 +3693,20 @@ operator is discussed in more detail in L. =item recv SOCKET,SCALAR,LENGTH,FLAGS -Receives a message on a socket. Attempts to receive LENGTH bytes of -data into variable SCALAR from the specified SOCKET filehandle. SCALAR -will be grown or shrunk to the length actually read. Takes the same -flags as the system call of the same name. Returns the address of the -sender if SOCKET's protocol supports this; returns an empty string -otherwise. If there's an error, returns the undefined value. This call -is actually implemented in terms of recvfrom(2) system call. See -L for examples. +Receives a message on a socket. Attempts to receive LENGTH characters +of data into variable SCALAR from the specified SOCKET filehandle. +SCALAR will be grown or shrunk to the length actually read. Takes the +same flags as the system call of the same name. Returns the address +of the sender if SOCKET's protocol supports this; returns an empty +string otherwise. If there's an error, returns the undefined value. +This call is actually implemented in terms of recvfrom(2) system call. +See L for examples. + +Note the I: depending on the status of the socket, either +(8-bit) bytes or characters are received. By default all sockets +operate on bytes, but for example if the socket has been changed using +binmode() to operate with the C<:utf8> discipline (see the C +pragma, L), the I/O will operate on characters, not bytes. =item redo LABEL @@ -4025,12 +4043,18 @@ See L for more details on unary operators and the comma operator. Sets FILEHANDLE's position, just like the C call of C. FILEHANDLE may be an expression whose value gives the name of the -filehandle. The values for WHENCE are C<0> to set the new position to -POSITION, C<1> to set it to the current position plus POSITION, and -C<2> to set it to EOF plus POSITION (typically negative). For WHENCE -you may use the constants C, C, and C -(start of the file, current position, end of the file) from the Fcntl -module. Returns C<1> upon success, C<0> otherwise. +filehandle. The values for WHENCE are C<0> to set the new position +I to POSITION, C<1> to set it to the current position plus +POSITION, and C<2> to set it to EOF plus POSITION (typically +negative). For WHENCE you may use the constants C, +C, and C (start of the file, current position, end +of the file) from the Fcntl module. Returns C<1> upon success, C<0> +otherwise. + +Note the I: even if the filehandle has been set to +operate on characters (for example by using the C<:utf8> open +discipline), tell() will return byte offsets, not character offsets +(because implementing that would render seek() and tell() rather slow). If you want to position file for C or C, don't use C--buffering makes its effect on the file's system position @@ -4049,8 +4073,8 @@ seek() to reset things. The C doesn't change the current position, but it I clear the end-of-file condition on the handle, so that the next C<< >> makes Perl try again to read something. We hope. -If that doesn't work (some stdios are particularly cantankerous), then -you may need something more like this: +If that doesn't work (some IO implementations are particularly +cantankerous), then you may need something more like this: for (;;) { for ($curpos = tell(FILE); $_ = ; @@ -4187,12 +4211,20 @@ documentation. =item send SOCKET,MSG,FLAGS -Sends a message on a socket. Takes the same flags as the system call -of the same name. On unconnected sockets you must specify a -destination to send TO, in which case it does a C C. Returns -the number of characters sent, or the undefined value if there is an -error. The C system call sendmsg(2) is currently unimplemented. -See L for examples. +Sends a message on a socket. Attemps to send the scalar MSG to the +SOCKET filehandle. Takes the same flags as the system call of the +same name. On unconnected sockets you must specify a destination to +send TO, in which case it does a C C. Returns the number of +characters sent, or the undefined value if there is an error. The C +system call sendmsg(2) is currently unimplemented. See +L for examples. + +Note the I: depending on the status of the socket, either +(8-bit) bytes or characters are sent. By default all sockets operate +on bytes, but for example if the socket has been changed using +binmode() to operate with the C<:utf8> discipline (see L, or +the C pragma, L), the I/O will operate on characters, not +bytes. =item setpgrp PID,PGRP @@ -5216,21 +5248,27 @@ See L for a kinder, gentler explanation of opening files. =item sysread FILEHANDLE,SCALAR,LENGTH -Attempts to read LENGTH bytes of data into variable SCALAR from the -specified FILEHANDLE, using the system call read(2). It bypasses stdio, -so mixing this with other kinds of reads, C, C, -C, C, or C can cause confusion because stdio -usually buffers data. Returns the number of bytes actually read, C<0> -at end of file, or undef if there was an error. SCALAR will be grown or -shrunk so that the last byte actually read is the last byte of the -scalar after the read. +Attempts to read LENGTH I of data into variable SCALAR from +the specified FILEHANDLE, using the system call read(2). It bypasses +buffered IO, so mixing this with other kinds of reads, C, +C, C, C, or C can cause confusion because +stdio usually buffers data. Returns the number of characters actually +read, C<0> at end of file, or undef if there was an error. SCALAR +will be grown or shrunk so that the last byte actually read is the +last byte of the scalar after the read. + +Note the I: depending on the status of the filehandle, +either (8-bit) bytes or characters are read. By default all +filehandles operate on bytes, but for example if the filehandle has +been opened with the C<:utf8> discipline (see L, and the C +pragma, L), the I/O will operate on characters, not bytes. An OFFSET may be specified to place the read data at some place in the string other than the beginning. A negative OFFSET specifies -placement at that many bytes counting backwards from the end of the -string. A positive OFFSET greater than the length of SCALAR results -in the string being padded to the required size with C<"\0"> bytes before -the result of the read is appended. +placement at that many characters counting backwards from the end of +the string. A positive OFFSET greater than the length of SCALAR +results in the string being padded to the required size with C<"\0"> +bytes before the result of the read is appended. There is no syseof() function, which is ok, since eof() doesn't work very well on device files (like ttys) anyway. Use sysread() and check @@ -5238,13 +5276,21 @@ for a return value for 0 to decide whether you're done. =item sysseek FILEHANDLE,POSITION,WHENCE -Sets FILEHANDLE's system position using the system call lseek(2). It -bypasses stdio, so mixing this with reads (other than C), -C, C, C, C, or C may cause confusion. -FILEHANDLE may be an expression whose value gives the name of the -filehandle. The values for WHENCE are C<0> to set the new position to -POSITION, C<1> to set the it to the current position plus POSITION, -and C<2> to set it to EOF plus POSITION (typically negative). +Sets FILEHANDLE's system position I using the system call +lseek(2). FILEHANDLE may be an expression whose value gives the name +of the filehandle. The values for WHENCE are C<0> to set the new +position to POSITION, C<1> to set the it to the current position plus +POSITION, and C<2> to set it to EOF plus POSITION (typically +negative). + +Note the I: even if the filehandle has been set to operate +on characters (for example by using the C<:utf8> discipline), tell() +will return byte offsets, not character offsets (because implementing +that would render sysseek() very slow). + +sysseek() bypasses normal buffered io, so mixing this with reads (other +than C, for example >< or read()) C, C, +C, C, or C may cause confusion. For WHENCE, you may also use the constants C, C, and C (start of the file, current position, end of the file) @@ -5317,28 +5363,40 @@ See L and L for details. =item syswrite FILEHANDLE,SCALAR -Attempts to write LENGTH bytes of data from variable SCALAR to the -specified FILEHANDLE, using the system call write(2). If LENGTH -is not specified, writes whole SCALAR. It bypasses stdio, so mixing -this with reads (other than C, C, C, -C, C, or C may cause confusion because stdio -usually buffers data. Returns the number of bytes actually written, -or C if there was an error. If the LENGTH is greater than -the available data in the SCALAR after the OFFSET, only as much -data as is available will be written. +Attempts to write LENGTH characters of data from variable SCALAR to +the specified FILEHANDLE, using the system call write(2). If LENGTH +is not specified, writes whole SCALAR. It bypasses buffered IO, so +mixing this with reads (other than C, C, C, +C, C, or C may cause confusion because stdio usually +buffers data. Returns the number of characters actually written, or +C if there was an error. If the LENGTH is greater than the +available data in the SCALAR after the OFFSET, only as much data as is +available will be written. An OFFSET may be specified to write the data from some part of the string other than the beginning. A negative OFFSET specifies writing -that many bytes counting backwards from the end of the string. In the -case the SCALAR is empty you can use OFFSET but only zero offset. +that many characters counting backwards from the end of the string. +In the case the SCALAR is empty you can use OFFSET but only zero offset. + +Note the I: depending on the status of the filehandle, +either (8-bit) bytes or characters are written. By default all +filehandles operate on bytes, but for example if the filehandle has +been opened with the C<:utf8> discipline (see L, and the open +pragma, L), the I/O will operate on characters, not bytes. =item tell FILEHANDLE =item tell -Returns the current position for FILEHANDLE, or -1 on error. FILEHANDLE -may be an expression whose value gives the name of the actual filehandle. -If FILEHANDLE is omitted, assumes the file last read. +Returns the current position I for FILEHANDLE, or -1 on +error. FILEHANDLE may be an expression whose value gives the name of +the actual filehandle. If FILEHANDLE is omitted, assumes the file +last read. + +Note the I: even if the filehandle has been set to +operate on characters (for example by using the C<:utf8> open +discipline), tell() will return byte offsets, not character offsets +(because that would render seek() and tell() rather slow). The return value of tell() for the standard streams like the STDIN depends on the operating system: it may return -1 or something else. @@ -5346,6 +5404,12 @@ tell() on pipes, fifos, and sockets usually returns -1. There is no C function. Use C for that. +Do not use tell() on a filehandle that has been opened using +sysopen(), use sysseek() for that as described above. Why? Because +sysopen() creates unbuffered, "raw", filehandles, while open() creates +buffered filehandles. sysseek() make sense only on the first kind, +tell() only makes sense on the second kind. + =item telldir DIRHANDLE Returns the current position of the C routines on DIRHANDLE. -- 2.7.4