From 56557ec28a8712984a0e9744fd7547e797ec9b6b Mon Sep 17 00:00:00 2001 From: nobu Date: Fri, 22 Mar 2019 11:04:59 +0000 Subject: [DOC] fix markups [ci skip] git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@67337 b2dd03c8-39d4-4d8f-98ff-823fe69b080e --- io.c | 334 ++++++++++++++++++++++++++++++++----------------------------------- 1 file changed, 160 insertions(+), 174 deletions(-) (limited to 'io.c') diff --git a/io.c b/io.c index 8cbe34706c..cd83f520af 100644 --- a/io.c +++ b/io.c @@ -2003,7 +2003,7 @@ static void clear_readconv(rb_io_t *fptr); * ios.rewind -> 0 * * Positions ios to the beginning of input, resetting - * lineno to zero. + * #lineno to zero. * * f = File.new("testfile") * f.readline #=> "This is line one\n" @@ -2089,14 +2089,14 @@ io_fillbuf(rb_io_t *fptr) * * Returns true if ios is at end of file that means * there are no more data to read. - * The stream must be opened for reading or an IOError will be + * The stream must be opened for reading or an IOError will be * raised. * * f = File.new("testfile") * dummy = f.readlines * f.eof #=> true * - * If ios is a stream such as pipe or socket, IO#eof? + * If ios is a stream such as pipe or socket, IO#eof? * blocks until the other end sends some data or closes it. * * r, w = IO.pipe @@ -2110,10 +2110,9 @@ io_fillbuf(rb_io_t *fptr) * r, w = IO.pipe * r.eof? # blocks forever * - * Note that IO#eof? reads data to the input byte buffer. - * So IO#sysread may not behave as you intend with - * IO#eof?, unless you call IO#rewind - * first (which is not available for some streams). + * Note that IO#eof? reads data to the input byte buffer. So + * IO#sysread may not behave as you intend with IO#eof?, unless you + * call IO#rewind first (which is not available for some streams). */ VALUE @@ -2145,7 +2144,7 @@ rb_io_eof(VALUE io) * Returns the current ``sync mode'' of ios. When sync mode is * true, all output is immediately flushed to the underlying operating * system and is not buffered by Ruby internally. See also - * IO#fsync. + * IO#fsync. * * f = File.new("testfile") * f.sync #=> false @@ -2170,7 +2169,7 @@ rb_io_sync(VALUE io) * Sets the ``sync mode'' to true or false. * When sync mode is true, all output is immediately flushed to the * underlying operating system and is not buffered internally. Returns - * the new state. See also IO#fsync. + * the new state. See also IO#fsync. * * f = File.new("testfile") * f.sync = true @@ -2197,12 +2196,11 @@ rb_io_set_sync(VALUE io, VALUE sync) * ios.fsync -> 0 or nil * * Immediately writes all buffered data in ios to disk. - * Note that fsync differs from - * using IO#sync=. The latter ensures that data is flushed - * from Ruby's buffers, but does not guarantee that the underlying - * operating system actually writes it to disk. + * Note that #fsync differs from using IO#sync=. The latter ensures + * that data is flushed from Ruby's buffers, but does not guarantee + * that the underlying operating system actually writes it to disk. * - * NotImplementedError is raised + * NotImplementedError is raised * if the underlying operating system does not support fsync(2). */ @@ -2251,8 +2249,8 @@ nogvl_fdatasync(void *ptr) * Immediately writes all buffered data in ios to disk. * * If the underlying operating system does not support fdatasync(2), - * IO#fsync is called instead (which might raise a - * NotImplementedError). + * IO#fsync is called instead (which might raise a + * NotImplementedError). */ static VALUE @@ -2305,7 +2303,7 @@ rb_io_fileno(VALUE io) * ios.pid -> integer * * Returns the process ID of a child process associated with - * ios. This will be set by IO.popen. + * ios. This will be set by IO.popen. * * pipe = IO.popen("-") * if pipe @@ -2868,7 +2866,7 @@ io_getpartial(int argc, VALUE *argv, VALUE io, VALUE opts, int nonblock) * The _outbuf_ will contain only the received data after the method call * even if it is not empty at the beginning. * - * It raises EOFError on end of file. + * It raises EOFError on end of file. * * readpartial is designed for streams such as pipe, socket, tty, etc. * It blocks only when no data immediately available. @@ -3581,12 +3579,12 @@ rb_io_gets_internal(VALUE io) * sep. A separator of +nil+ reads the entire * contents, and a zero-length separator reads the input a paragraph at * a time (two successive newlines in the input separate paragraphs). - * The stream must be opened for reading or an IOError - * will be raised. The line read in will be returned and also assigned - * to $_. Returns +nil+ if called at end of - * file. If the first argument is an integer, or optional second - * argument is given, the returning string would not be longer than the - * given value in bytes. + * The stream must be opened for reading or an IOError will be raised. + * The line read in will be returned and also assigned to + * $_. Returns +nil+ if called at end of file. If the + * first argument is an integer, or optional second argument is given, + * the returning string would not be longer than the given value in + * bytes. * * File.new("testfile").gets #=> "This is line one\n" * $_ #=> "This is line one\n" @@ -3620,12 +3618,12 @@ rb_io_gets_m(int argc, VALUE *argv, VALUE io) * ios.lineno -> integer * * Returns the current line number in ios. The stream must be - * opened for reading. lineno counts the number of times - * #gets is called rather than the number of newlines encountered. The two - * values will differ if #gets is called with a separator other than newline. + * opened for reading. #lineno counts the number of times #gets is called + * rather than the number of newlines encountered. The two values will + * differ if #gets is called with a separator other than newline. * * Methods that use $/ like #each, #lines and #readline will - * also increment lineno. + * also increment #lineno. * * See also the $. variable. * @@ -3681,8 +3679,7 @@ rb_io_set_lineno(VALUE io, VALUE lineno) * ios.readline(limit [, getline_args]) -> string * ios.readline(sep, limit [, getline_args]) -> string * - * Reads a line as with IO#gets, but raises an - * EOFError on end of file. + * Reads a line as with IO#gets, but raises an EOFError on end of file. */ static VALUE @@ -3711,7 +3708,7 @@ static VALUE io_readlines(const struct getline_arg *arg, VALUE io); * If the first argument is an integer, or an * optional second argument is given, the returning string would not be * longer than the given value in bytes. The stream must be opened for - * reading or an IOError will be raised. + * reading or an IOError will be raised. * * f = File.new("testfile") * f.readlines[0] #=> "This is line one\n" @@ -3759,7 +3756,7 @@ io_readlines(const struct getline_arg *arg, VALUE io) * * Executes the block for every line in ios, where lines are * separated by sep. ios must be opened for - * reading or an IOError will be raised. + * reading or an IOError will be raised. * * If no block is given, an enumerator is returned instead. * @@ -3793,7 +3790,7 @@ rb_io_each_line(int argc, VALUE *argv, VALUE io) } /* - * This is a deprecated alias for each_line. + * This is a deprecated alias for #each_line. */ static VALUE @@ -3812,7 +3809,7 @@ rb_io_lines(int argc, VALUE *argv, VALUE io) * * Calls the given block once for each byte (0..255) in ios, * passing the byte as an argument. The stream must be opened for - * reading or an IOError will be raised. + * reading or an IOError will be raised. * * If no block is given, an enumerator is returned instead. * @@ -3844,7 +3841,7 @@ rb_io_each_byte(VALUE io) } /* - * This is a deprecated alias for each_byte. + * This is a deprecated alias for #each_byte. */ static VALUE @@ -3970,7 +3967,7 @@ io_getc(rb_io_t *fptr, rb_encoding *enc) * * Calls the given block once for each character in ios, * passing the character as an argument. The stream must be opened for - * reading or an IOError will be raised. + * reading or an IOError will be raised. * * If no block is given, an enumerator is returned instead. * @@ -3998,7 +3995,7 @@ rb_io_each_char(VALUE io) } /* - * This is a deprecated alias for each_char. + * This is a deprecated alias for #each_char. */ static VALUE @@ -4018,9 +4015,9 @@ rb_io_chars(VALUE io) * ios.each_codepoint -> an_enumerator * ios.codepoints -> an_enumerator * - * Passes the Integer ordinal of each character in ios, + * Passes the Integer ordinal of each character in ios, * passing the codepoint as an argument. The stream must be opened for - * reading or an IOError will be raised. + * reading or an IOError will be raised. * * If no block is given, an enumerator is returned instead. * @@ -4126,7 +4123,7 @@ rb_io_each_codepoint(VALUE io) } /* - * This is a deprecated alias for each_codepoint. + * This is a deprecated alias for #each_codepoint. */ static VALUE @@ -4170,7 +4167,7 @@ rb_io_getc(VALUE io) * ios.readchar -> string * * Reads a one-character string from ios. Raises an - * EOFError on end of file. + * EOFError on end of file. * * f = File.new("testfile") * f.readchar #=> "h" @@ -4229,8 +4226,8 @@ rb_io_getbyte(VALUE io) * call-seq: * ios.readbyte -> integer * - * Reads a byte as with IO#getbyte, but raises an - * EOFError on end of file. + * Reads a byte as with IO#getbyte, but raises an EOFError on end of + * file. */ static VALUE @@ -4253,7 +4250,7 @@ rb_io_readbyte(VALUE io) * such that a subsequent buffered read will return it. Only one byte * may be pushed back before a subsequent read operation (that is, * you will be able to read only the last of several bytes that have been pushed - * back). Has no effect with unbuffered reads (such as IO#sysread). + * back). Has no effect with unbuffered reads (such as IO#sysread). * * f = File.new("testfile") #=> # * b = f.getbyte #=> 0x38 @@ -4292,7 +4289,7 @@ rb_io_ungetbyte(VALUE io, VALUE b) * such that a subsequent buffered character read will return it. Only one character * may be pushed back before a subsequent read operation (that is, * you will be able to read only the last of several characters that have been pushed - * back). Has no effect with unbuffered reads (such as IO#sysread). + * back). Has no effect with unbuffered reads (such as IO#sysread). * * f = File.new("testfile") #=> # * c = f.getc #=> "8" @@ -4819,12 +4816,11 @@ rb_io_close(VALUE io) * * Closes ios and flushes any pending writes to the operating * system. The stream is unavailable for any further data operations; - * an IOError is raised if such an attempt is made. I/O - * streams are automatically closed when they are claimed by the - * garbage collector. + * an IOError is raised if such an attempt is made. I/O streams are + * automatically closed when they are claimed by the garbage collector. * - * If ios is opened by IO.popen, - * close sets $?. + * If ios is opened by IO.popen, #close sets + * $?. * * Calling this method on closed IO object is just ignored since Ruby 2.3. */ @@ -4914,7 +4910,7 @@ rb_io_closed(VALUE io) * * Closes the read end of a duplex I/O stream (i.e., one that contains * both a read and a write stream, such as a pipe). Will raise an - * IOError if the stream is not duplexed. + * IOError if the stream is not duplexed. * * f = IO.popen("/bin/sh","r+") * f.close_read @@ -4975,7 +4971,7 @@ rb_io_close_read(VALUE io) * * Closes the write end of a duplex I/O stream (i.e., one that contains * both a read and a write stream, such as a pipe). Will raise an - * IOError if the stream is not duplexed. + * IOError if the stream is not duplexed. * * f = IO.popen("/bin/sh","r+") * f.close_write @@ -5028,8 +5024,8 @@ rb_io_close_write(VALUE io) * ios.sysseek(offset, whence=IO::SEEK_SET) -> integer * * Seeks to a given offset in the stream according to the value - * of whence (see IO#seek for values of - * whence). Returns the new offset into the file. + * of whence (see IO#seek for values of whence). Returns + * the new offset into the file. * * f = File.new("testfile") * f.sysseek(-13, IO::SEEK_END) #=> 53 @@ -5070,7 +5066,7 @@ rb_io_sysseek(int argc, VALUE *argv, VALUE io) * Writes the given string to ios using a low-level write. * Returns the number of bytes written. Do not mix with other methods * that write to ios or you may get unpredictable results. - * Raises SystemCallError on error. + * Raises SystemCallError on error. * * f = File.new("out", "w") * f.syswrite("ABCDEF") #=> 6 @@ -5117,8 +5113,7 @@ rb_io_syswrite(VALUE io, VALUE str) * The _outbuf_ will contain only the received data after the method call * even if it is not empty at the beginning. * - * Raises SystemCallError on error and - * EOFError at end of file. + * Raises SystemCallError on error and EOFError at end of file. * * f = File.new("testfile") * f.sysread(16) #=> "This is line one" @@ -5212,9 +5207,8 @@ pread_internal_call(VALUE arg) * This bypasses any userspace buffering of the IO layer. * If the optional outbuf argument is present, it must * reference a String, which will receive the data. - * Raises SystemCallError on error, EOFError - * at end of file and NotImplementedError if platform does not - * implement the system call. + * Raises SystemCallError on error, EOFError at end of file and + * NotImplementedError if platform does not implement the system call. * * File.write("testfile", "This is line one\nThis is line two\n") * File.open("testfile") do |f| @@ -5283,7 +5277,7 @@ internal_pwrite_func(void *ptr) * same IO object for reading the file at various locations. * This bypasses any userspace buffering of the IO layer. * Returns the number of bytes written. - * Raises SystemCallError on error and NotImplementedError + * Raises SystemCallError on error and NotImplementedError * if platform does not implement the system call. * * File.open("out", "w") do |f| @@ -6795,7 +6789,7 @@ pipe_close(VALUE io) * * Runs the specified command as a subprocess; the subprocess's * standard input and output will be connected to the returned - * IO object. + * IO object. * * The PID of the started process can be obtained by IO#pid method. * @@ -6814,7 +6808,7 @@ pipe_close(VALUE io) * If cmd is an +Array+ of +String+, * then it will be used as the subprocess's +argv+ bypassing a shell. * The array can contain a hash at first for environments and - * a hash at last for options similar to spawn. + * a hash at last for options similar to #spawn. * * The default mode for the new file object is ``r'', * but mode may be set to any of the modes listed in the description for class IO. @@ -6836,15 +6830,13 @@ pipe_close(VALUE io) * ls_result_with_error = ls_io.read * } * - * Raises exceptions which IO.pipe and - * Kernel.spawn raise. + * Raises exceptions which IO.pipe and Kernel.spawn raise. * * If a block is given, Ruby will run the command as a child connected * to Ruby with a pipe. Ruby's end of the pipe will be passed as a * parameter to the block. * At the end of block, Ruby closes the pipe and sets $?. - * In this case IO.popen returns - * the value of the block. + * In this case IO.popen returns the value of the block. * * If a block is given with a _cmd_ of ``-'', * the block will be run in two separate processes: once in the parent, @@ -6989,11 +6981,11 @@ rb_open_file(int argc, const VALUE *argv, VALUE io) * File.open(filename, mode="r" [, opt]) {|file| block } -> obj * File.open(filename [, mode [, perm]] [, opt]) {|file| block } -> obj * - * With no associated block, File.open is a synonym for + * With no associated block, File.open is a synonym for * File.new. If the optional code block is given, it will * be passed the opened +file+ as an argument and the File object will * automatically be closed when the block terminates. The value of the block - * will be returned from File.open. + * will be returned from File.open. * * If a file is being created, its initial permissions may be set using the * +perm+ parameter. See File.new for further discussion. @@ -7008,7 +7000,7 @@ rb_open_file(int argc, const VALUE *argv, VALUE io) * IO.open(fd, mode="r" [, opt]) -> io * IO.open(fd, mode="r" [, opt]) {|io| block } -> obj * - * With no associated block, IO.open is a synonym for IO.new. If + * With no associated block, IO.open is a synonym for IO.new. If * the optional code block is given, it will be passed +io+ as an argument, * and the IO object will automatically be closed when the block terminates. * In this instance, IO.open returns the value of the block. @@ -7033,7 +7025,7 @@ rb_io_s_open(int argc, VALUE *argv, VALUE klass) * IO.sysopen(path, [mode, [perm]]) -> integer * * Opens the given path, returning the underlying file descriptor as a - * Integer. + * Integer. * * IO.sysopen("testfile") #=> 3 */ @@ -7493,8 +7485,7 @@ rb_io_init_copy(VALUE dest, VALUE io) * ios.printf(format_string [, obj, ...]) -> nil * * Formats and writes to ios, converting parameters under - * control of the format string. See Kernel#sprintf - * for details. + * control of the format string. See Kernel#sprintf for details. */ VALUE @@ -7617,11 +7608,10 @@ rb_f_print(int argc, const VALUE *argv) * call-seq: * ios.putc(obj) -> obj * - * If obj is Numeric, write the character whose code is - * the least-significant byte of obj. - * If obj is String, write the first character - * of obj to ios. - * Otherwise, raise TypeError. + * If obj is Numeric, write the character whose code is the + * least-significant byte of obj. If obj is String, + * write the first character of obj to ios. Otherwise, + * raise TypeError. * * $stdout.putc "A" * $stdout.putc 65 @@ -8138,8 +8128,8 @@ rb_io_make_open_file(VALUE obj) * "t" Text file mode * * The exclusive access mode ("x") can be used together with "w" to ensure - * the file is created. Errno::EEXIST is raised when it already - * exists. It may not be supported with all kinds of streams (e.g. pipes). + * the file is created. Errno::EEXIST is raised when it already exists. + * It may not be supported with all kinds of streams (e.g. pipes). * * When the open mode of original IO is read only, the mode cannot be * changed to be writable. Similarly, the open mode cannot be changed from @@ -8229,7 +8219,7 @@ rb_io_make_open_file(VALUE obj) * io.puts "Hello, World!" * * Both of above print "Hello, World!" in UTF-16LE to standard error output - * with converting EOL generated by puts to CR. + * with converting EOL generated by #puts to CR. */ static VALUE @@ -8307,8 +8297,7 @@ rb_io_initialize(int argc, VALUE *argv, VALUE io) * * The new File object is buffered mode (or non-sync mode), unless * +filename+ is a tty. - * See IO#flush, IO#fsync, IO#fdatasync, and IO#sync= - * about sync mode. + * See IO#flush, IO#fsync, IO#fdatasync, and IO#sync= about sync mode. * * === Examples * @@ -8354,7 +8343,7 @@ rb_io_s_new(int argc, VALUE *argv, VALUE klass) * call-seq: * IO.for_fd(fd, mode [, opt]) -> io * - * Synonym for IO.new. + * Synonym for IO.new. * */ @@ -8882,7 +8871,7 @@ static VALUE argf_readline(int, VALUE *, VALUE); * readline(limit) -> string * readline(sep, limit) -> string * - * Equivalent to Kernel::gets, except + * Equivalent to Kernel::gets, except * +readline+ raises +EOFError+ at end of file. */ @@ -9314,17 +9303,17 @@ advice_arg_check(VALUE advice) * * If an error occurs, one of the following exceptions will be raised: * - * IOError:: The IO stream is closed. - * Errno::EBADF:: + * IOError:: The IO stream is closed. + * Errno::EBADF:: * The file descriptor of the current file is invalid. - * Errno::EINVAL:: An invalid value for _advice_ was given. - * Errno::ESPIPE:: + * Errno::EINVAL:: An invalid value for _advice_ was given. + * Errno::ESPIPE:: * The file descriptor of the current file refers to a FIFO or - * pipe. (Linux raises Errno::EINVAL in this case). - * TypeError:: + * pipe. (Linux raises Errno::EINVAL in this case). + * TypeError:: * Either _advice_ was not a Symbol, or one of the - * other arguments was not an Integer. - * RangeError:: One of the arguments given was too big/small. + * other arguments was not an Integer. + * RangeError:: One of the arguments given was too big/small. * * This list is not exhaustive; other Errno:: exceptions are also possible. */ @@ -9357,29 +9346,28 @@ rb_io_advise(int argc, VALUE *argv, VALUE io) * IO.select(read_array [, write_array [, error_array [, timeout]]]) -> array or nil * * Calls select(2) system call. - * It monitors given arrays of IO objects, waits until one or more - * of IO objects are ready for reading, are ready for writing, - * and have pending exceptions respectively, and returns an array that - * contains arrays of those IO objects. It will return +nil+ - * if optional timeout value is given and no IO object - * is ready in timeout seconds. - * - * IO.select peeks the buffer of IO objects for testing readability. - * If the IO buffer is not empty, - * IO.select immediately notifies readability. - * This "peek" only happens for IO objects. - * It does not happen for IO-like objects such as OpenSSL::SSL::SSLSocket. - * - * The best way to use IO.select is invoking it - * after nonblocking methods such as read_nonblock, write_nonblock, etc. - * The methods raise an exception which is extended by - * IO::WaitReadable or IO::WaitWritable. - * The modules notify how the caller should wait with IO.select. - * If IO::WaitReadable is raised, the caller should wait for reading. - * If IO::WaitWritable is raised, the caller should wait for writing. - * - * So, blocking read (readpartial) can be emulated using - * read_nonblock and IO.select as follows: + * It monitors given arrays of IO objects, waits until one or more of + * IO objects are ready for reading, are ready for writing, and have + * pending exceptions respectively, and returns an array that contains + * arrays of those IO objects. It will return +nil+ if optional + * timeout value is given and no IO object is ready in + * timeout seconds. + * + * IO.select peeks the buffer of IO objects for testing readability. + * If the IO buffer is not empty, IO.select immediately notifies + * readability. This "peek" only happens for IO objects. It does not + * happen for IO-like objects such as OpenSSL::SSL::SSLSocket. + * + * The best way to use IO.select is invoking it after nonblocking + * methods such as #read_nonblock, #write_nonblock, etc. The methods + * raise an exception which is extended by IO::WaitReadable or + * IO::WaitWritable. The modules notify how the caller should wait + * with IO.select. If IO::WaitReadable is raised, the caller should + * wait for reading. If IO::WaitWritable is raised, the caller should + * wait for writing. + * + * So, blocking read (#readpartial) can be emulated using + * #read_nonblock and IO.select as follows: * * begin * result = io_like.read_nonblock(maxlen) @@ -9391,57 +9379,57 @@ rb_io_advise(int argc, VALUE *argv, VALUE io) * retry * end * - * Especially, the combination of nonblocking methods and - * IO.select is preferred for IO like - * objects such as OpenSSL::SSL::SSLSocket. - * It has to_io method to return underlying IO object. - * IO.select calls to_io to obtain the file descriptor to wait. + * Especially, the combination of nonblocking methods and IO.select is + * preferred for IO like objects such as OpenSSL::SSL::SSLSocket. It + * has #to_io method to return underlying IO object. IO.select calls + * #to_io to obtain the file descriptor to wait. * - * This means that readability notified by IO.select doesn't mean - * readability from OpenSSL::SSL::SSLSocket object. + * This means that readability notified by IO.select doesn't mean + * readability from OpenSSL::SSL::SSLSocket object. * - * The most likely situation is that OpenSSL::SSL::SSLSocket buffers some data. - * IO.select doesn't see the buffer. - * So IO.select can block when OpenSSL::SSL::SSLSocket#readpartial doesn't block. + * The most likely situation is that OpenSSL::SSL::SSLSocket buffers + * some data. IO.select doesn't see the buffer. So IO.select can + * block when OpenSSL::SSL::SSLSocket#readpartial doesn't block. * * However, several more complicated situations exist. * * SSL is a protocol which is sequence of records. * The record consists of multiple bytes. - * So, the remote side of SSL sends a partial record, - * IO.select notifies readability but - * OpenSSL::SSL::SSLSocket cannot decrypt a byte and - * OpenSSL::SSL::SSLSocket#readpartial will block. + * So, the remote side of SSL sends a partial record, IO.select + * notifies readability but OpenSSL::SSL::SSLSocket cannot decrypt a + * byte and OpenSSL::SSL::SSLSocket#readpartial will block. * * Also, the remote side can request SSL renegotiation which forces * the local SSL engine to write some data. - * This means OpenSSL::SSL::SSLSocket#readpartial may - * invoke write system call and it can block. - * In such a situation, OpenSSL::SSL::SSLSocket#read_nonblock - * raises IO::WaitWritable instead of blocking. - * So, the caller should wait for ready for writability as above example. + * This means OpenSSL::SSL::SSLSocket#readpartial may invoke #write + * system call and it can block. + * In such a situation, OpenSSL::SSL::SSLSocket#read_nonblock raises + * IO::WaitWritable instead of blocking. + * So, the caller should wait for ready for writability as above + * example. * - * The combination of nonblocking methods and IO.select is - * also useful for streams such as tty, pipe socket socket when - * multiple processes read from a stream. + * The combination of nonblocking methods and IO.select is also useful + * for streams such as tty, pipe socket socket when multiple processes + * read from a stream. * * Finally, Linux kernel developers don't guarantee that * readability of select(2) means readability of following read(2) even * for a single process. * See select(2) manual on GNU/Linux system. * - * Invoking IO.select before IO#readpartial works well as usual. - * However it is not the best way to use IO.select. + * Invoking IO.select before IO#readpartial works well as usual. + * However it is not the best way to use IO.select. * * The writability notified by select(2) doesn't show * how many bytes are writable. - * IO#write method blocks until given whole string is written. - * So, IO#write(two or more bytes) can block after writability is notified by IO.select. - * IO#write_nonblock is required to avoid the blocking. + * IO#write method blocks until given whole string is written. + * So, IO#write(two or more bytes) can block after + * writability is notified by IO.select. IO#write_nonblock is required + * to avoid the blocking. * - * Blocking write (write) can be emulated using - * write_nonblock and IO.select as follows: - * IO::WaitReadable should also be rescued for SSL renegotiation in OpenSSL::SSL::SSLSocket. + * Blocking write (#write) can be emulated using #write_nonblock and + * IO.select as follows: IO::WaitReadable should also be rescued for + * SSL renegotiation in OpenSSL::SSL::SSLSocket. * * while 0 < string.bytesize * begin @@ -9457,9 +9445,9 @@ rb_io_advise(int argc, VALUE *argv, VALUE io) * end * * === Parameters - * read_array:: an array of IO objects that wait until ready for read - * write_array:: an array of IO objects that wait until ready for write - * error_array:: an array of IO objects that wait for exceptions + * read_array:: an array of IO objects that wait until ready for read + * write_array:: an array of IO objects that wait until ready for write + * error_array:: an array of IO objects that wait for exceptions * timeout:: a numeric value in second * * === Example @@ -9910,9 +9898,9 @@ rb_fcntl(VALUE io, VALUE req, VALUE arg) * query file-oriented I/O streams. Arguments and results are platform * dependent. If arg is a number, its value is passed * directly. If it is a string, it is interpreted as a binary sequence - * of bytes (Array#pack might be a useful way to build this - * string). On Unix platforms, see fcntl(2) for details. - * Not implemented on all platforms. + * of bytes (Array#pack might be a useful way to build this string). On + * Unix platforms, see fcntl(2) for details. Not + * implemented on all platforms. */ static VALUE @@ -10166,7 +10154,7 @@ pipe_pair_close(VALUE rw) * IO.pipe(...) {|read_io, write_io| ... } * * Creates a pair of pipe endpoints (connected to each other) and - * returns them as a two-element array of IO objects: + * returns them as a two-element array of IO objects: * [ read_io, write_io ]. * * If a block is given, the block is called and @@ -10463,8 +10451,8 @@ seek_before_access(VALUE argp) * IO.read(name, [length [, offset]] [, opt] ) -> string * * Opens the file, optionally seeks to the given +offset+, then returns - * +length+ bytes (defaulting to the rest of the file). read - * ensures the file is closed before returning. + * +length+ bytes (defaulting to the rest of the file). #read ensures + * the file is closed before returning. * * If +name+ starts with a pipe character ("|"), a subprocess is * created in the same way as Kernel#open, and its output is returned. @@ -10529,10 +10517,10 @@ rb_io_s_read(int argc, VALUE *argv, VALUE io) * call-seq: * IO.binread(name, [length [, offset]] ) -> string * - * Opens the file, optionally seeks to the given offset, then returns - * length bytes (defaulting to the rest of the file). - * binread ensures the file is closed before returning. - * The open mode would be "rb:ASCII-8BIT". + * Opens the file, optionally seeks to the given offset, then + * returns length bytes (defaulting to the rest of the file). + * #binread ensures the file is closed before returning. The open mode + * would be "rb:ASCII-8BIT". * * IO.binread("testfile") #=> "This is line one\nThis is line two\nThis is line three\nAnd so on...\n" * IO.binread("testfile", 20) #=> "This is line one\nThi" @@ -10635,10 +10623,9 @@ io_s_write(int argc, VALUE *argv, VALUE klass, int binary) * IO.write(name, string [, offset] [, opt]) -> integer * * Opens the file, optionally seeks to the given offset, writes - * string, then returns the length written. - * write ensures the file is closed before returning. - * If offset is not given in write mode, the file is truncated. - * Otherwise, it is not truncated. + * string, then returns the length written. #write ensures the + * file is closed before returning. If offset is not given in + * write mode, the file is truncated. Otherwise, it is not truncated. * * IO.write("testfile", "0123456789", 20) #=> 10 * # File could contain: "This is line one\nThi0123456789two\nThis is line three\nAnd so on...\n" @@ -10684,8 +10671,8 @@ rb_io_s_write(int argc, VALUE *argv, VALUE io) * IO.binwrite(name, string, [offset] ) -> integer * IO.binwrite(name, string, [offset], open_args ) -> integer * - * Same as IO.write except opening the file in binary mode - * and ASCII-8BIT encoding ("wb:ASCII-8BIT"). + * Same as IO.write except opening the file in binary mode and + * ASCII-8BIT encoding ("wb:ASCII-8BIT"). */ static VALUE @@ -11578,9 +11565,8 @@ copy_stream_finalize(VALUE arg) * * IO.copy_stream copies src to dst. * src and dst is either a filename or an IO-like object. - * IO-like object for src should have readpartial or - * read method. - * IO-like object for dst should have write method. + * IO-like object for src should have #readpartial or #read + * method. IO-like object for dst should have #write method. * (Specialized mechanisms, such as sendfile system call, may be used * on appropriate situation.) * @@ -12103,11 +12089,11 @@ static VALUE argf_getpartial(int argc, VALUE *argv, VALUE argf, VALUE opts, * The _outbuf_ will contain only the received data after the method call * even if it is not empty at the beginning. * - * It raises EOFError on end of ARGF stream. + * It raises EOFError on end of ARGF stream. * Since ARGF stream is a concatenation of multiple files, * internally EOF is occur for each file. * ARGF.readpartial returns empty strings for EOFs except the last one and - * raises EOFError for the last one. + * raises EOFError for the last one. * */ @@ -12417,7 +12403,7 @@ argf_each_line(int argc, VALUE *argv, VALUE argf) } /* - * This is a deprecated alias for each_line. + * This is a deprecated alias for #each_line. */ static VALUE @@ -12464,7 +12450,7 @@ argf_each_byte(VALUE argf) } /* - * This is a deprecated alias for each_byte. + * This is a deprecated alias for #each_byte. */ static VALUE @@ -12503,7 +12489,7 @@ argf_each_char(VALUE argf) } /* - * This is a deprecated alias for each_char. + * This is a deprecated alias for #each_char. */ static VALUE @@ -12542,7 +12528,7 @@ argf_each_codepoint(VALUE argf) } /* - * This is a deprecated alias for each_codepoint. + * This is a deprecated alias for #each_codepoint. */ static VALUE -- cgit v1.2.3