diff options
author | nobu <nobu@b2dd03c8-39d4-4d8f-98ff-823fe69b080e> | 2019-03-22 11:04:59 +0000 |
---|---|---|
committer | nobu <nobu@b2dd03c8-39d4-4d8f-98ff-823fe69b080e> | 2019-03-22 11:04:59 +0000 |
commit | 56557ec28a8712984a0e9744fd7547e797ec9b6b (patch) | |
tree | a9fdee9c62afc0d8c50e56414708b00861a633ea /io.c | |
parent | c671f836b4d123bf86bce6defe42c87caef582f8 (diff) | |
download | ruby-56557ec28a8712984a0e9744fd7547e797ec9b6b.tar.gz |
[DOC] fix markups [ci skip]
git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@67337 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
Diffstat (limited to 'io.c')
-rw-r--r-- | io.c | 334 |
1 files changed, 160 insertions, 174 deletions
@@ -2003,7 +2003,7 @@ static void clear_readconv(rb_io_t *fptr); * ios.rewind -> 0 * * Positions <em>ios</em> to the beginning of input, resetting - * <code>lineno</code> 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 <em>ios</em> is at end of file that means * there are no more data to read. - * The stream must be opened for reading or an <code>IOError</code> 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 <em>ios</em> is a stream such as pipe or socket, <code>IO#eof?</code> + * If <em>ios</em> 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 <code>IO#eof?</code> reads data to the input byte buffer. - * So <code>IO#sysread</code> may not behave as you intend with - * <code>IO#eof?</code>, unless you call <code>IO#rewind</code> - * 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 <em>ios</em>. When sync mode is * true, all output is immediately flushed to the underlying operating * system and is not buffered by Ruby internally. See also - * <code>IO#fsync</code>. + * IO#fsync. * * f = File.new("testfile") * f.sync #=> false @@ -2170,7 +2169,7 @@ rb_io_sync(VALUE io) * Sets the ``sync mode'' to <code>true</code> or <code>false</code>. * 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 <code>IO#fsync</code>. + * 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 <em>ios</em> to disk. - * Note that <code>fsync</code> differs from - * using <code>IO#sync=</code>. 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. * - * <code>NotImplementedError</code> is raised + * NotImplementedError is raised * if the underlying operating system does not support <em>fsync(2)</em>. */ @@ -2251,8 +2249,8 @@ nogvl_fdatasync(void *ptr) * Immediately writes all buffered data in <em>ios</em> to disk. * * If the underlying operating system does not support <em>fdatasync(2)</em>, - * <code>IO#fsync</code> is called instead (which might raise a - * <code>NotImplementedError</code>). + * 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 - * <em>ios</em>. This will be set by <code>IO.popen</code>. + * <em>ios</em>. 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 <code>EOFError</code> 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) * <i>sep</i>. 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 <code>IOError</code> - * will be raised. The line read in will be returned and also assigned - * to <code>$_</code>. 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 + * <code>$_</code>. 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 <em>ios</em>. The stream must be - * opened for reading. <code>lineno</code> 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 <code>$/</code> like #each, #lines and #readline will - * also increment <code>lineno</code>. + * also increment #lineno. * * See also the <code>$.</code> 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 <code>IO#gets</code>, but raises an - * <code>EOFError</code> 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 <code>IOError</code> 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 <em>ios</em>, where lines are * separated by <i>sep</i>. <em>ios</em> must be opened for - * reading or an <code>IOError</code> 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 <code>each_line</code>. + * 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 <em>ios</em>, * passing the byte as an argument. The stream must be opened for - * reading or an <code>IOError</code> 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 <code>each_byte</code>. + * 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 <em>ios</em>, * passing the character as an argument. The stream must be opened for - * reading or an <code>IOError</code> 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 <code>each_char</code>. + * 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 <code>Integer</code> ordinal of each character in <i>ios</i>, + * Passes the Integer ordinal of each character in <i>ios</i>, * passing the codepoint as an argument. The stream must be opened for - * reading or an <code>IOError</code> 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 <code>each_codepoint</code>. + * 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 <em>ios</em>. Raises an - * <code>EOFError</code> 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 <code>IO#getbyte</code>, but raises an - * <code>EOFError</code> 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 <code>IO#sysread</code>). + * back). Has no effect with unbuffered reads (such as IO#sysread). * * f = File.new("testfile") #=> #<File: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 <code>IO#sysread</code>). + * back). Has no effect with unbuffered reads (such as IO#sysread). * * f = File.new("testfile") #=> #<File:testfile> * c = f.getc #=> "8" @@ -4819,12 +4816,11 @@ rb_io_close(VALUE io) * * Closes <em>ios</em> and flushes any pending writes to the operating * system. The stream is unavailable for any further data operations; - * an <code>IOError</code> 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 <em>ios</em> is opened by <code>IO.popen</code>, - * <code>close</code> sets <code>$?</code>. + * If <em>ios</em> is opened by IO.popen, #close sets + * <code>$?</code>. * * 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 - * <code>IOError</code> 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 - * <code>IOError</code> 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 <i>offset</i> in the stream according to the value - * of <i>whence</i> (see <code>IO#seek</code> for values of - * <i>whence</i>). Returns the new offset into the file. + * of <i>whence</i> (see IO#seek for values of <i>whence</i>). 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 <em>ios</em> using a low-level write. * Returns the number of bytes written. Do not mix with other methods * that write to <em>ios</em> or you may get unpredictable results. - * Raises <code>SystemCallError</code> 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 <code>SystemCallError</code> on error and - * <code>EOFError</code> 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 <i>outbuf</i> argument is present, it must * reference a String, which will receive the data. - * Raises <code>SystemCallError</code> on error, <code>EOFError</code> - * at end of file and <code>NotImplementedError</code> 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 <code>SystemCallError</code> on error and <code>NotImplementedError</code> + * 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 - * <code>IO</code> 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 <i>cmd</i> 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 <code>spawn</code>. + * a hash at last for options similar to #spawn. * * The default mode for the new file object is ``r'', * but <i>mode</i> 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 <code>IO.pipe</code> and - * <code>Kernel.spawn</code> 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 <code>$?</code>. - * In this case <code>IO.popen</code> 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 ``<code>-</code>'', * 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, <code>File.open</code> 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 <code>File.open</code>. + * 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, <code>IO.open</code> 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 - * <code>Integer</code>. + * 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 <em>ios</em>, converting parameters under - * control of the format string. See <code>Kernel#sprintf</code> - * 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 <i>obj</i> is <code>Numeric</code>, write the character whose code is - * the least-significant byte of <i>obj</i>. - * If <i>obj</i> is <code>String</code>, write the first character - * of <i>obj</i> to <em>ios</em>. - * Otherwise, raise <code>TypeError</code>. + * If <i>obj</i> is Numeric, write the character whose code is the + * least-significant byte of <i>obj</i>. If <i>obj</i> is String, + * write the first character of <i>obj</i> to <em>ios</em>. 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. <code>Errno::EEXIST</code> 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 <code>puts</code> 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 <code>IO#sync=</code> - * 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 <code>IO.new</code>. + * Synonym for IO.new. * */ @@ -8882,7 +8871,7 @@ static VALUE argf_readline(int, VALUE *, VALUE); * readline(limit) -> string * readline(sep, limit) -> string * - * Equivalent to <code>Kernel::gets</code>, 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: * - * <code>IOError</code>:: The <code>IO</code> stream is closed. - * <code>Errno::EBADF</code>:: + * IOError:: The IO stream is closed. + * Errno::EBADF:: * The file descriptor of the current file is invalid. - * <code>Errno::EINVAL</code>:: An invalid value for _advice_ was given. - * <code>Errno::ESPIPE</code>:: + * 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 <code>Errno::EINVAL</code> in this case). - * <code>TypeError</code>:: + * pipe. (Linux raises Errno::EINVAL in this case). + * TypeError:: * Either _advice_ was not a Symbol, or one of the - * other arguments was not an <code>Integer</code>. - * <code>RangeError</code>:: 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 <code>IO</code> objects, waits until one or more - * of <code>IO</code> 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 <i>timeout</i> value is given and no <code>IO</code> object - * is ready in <i>timeout</i> seconds. - * - * <code>IO.select</code> peeks the buffer of <code>IO</code> objects for testing readability. - * If the <code>IO</code> buffer is not empty, - * <code>IO.select</code> immediately notifies readability. - * This "peek" only happens for <code>IO</code> objects. - * It does not happen for IO-like objects such as OpenSSL::SSL::SSLSocket. - * - * The best way to use <code>IO.select</code> is invoking it - * after nonblocking methods such as <code>read_nonblock</code>, <code>write_nonblock</code>, etc. - * The methods raise an exception which is extended by - * <code>IO::WaitReadable</code> or <code>IO::WaitWritable</code>. - * The modules notify how the caller should wait with <code>IO.select</code>. - * If <code>IO::WaitReadable</code> is raised, the caller should wait for reading. - * If <code>IO::WaitWritable</code> is raised, the caller should wait for writing. - * - * So, blocking read (<code>readpartial</code>) can be emulated using - * <code>read_nonblock</code> and <code>IO.select</code> 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 + * <i>timeout</i> value is given and no IO object is ready in + * <i>timeout</i> 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 - * <code>IO.select</code> is preferred for <code>IO</code> like - * objects such as <code>OpenSSL::SSL::SSLSocket</code>. - * It has <code>to_io</code> method to return underlying <code>IO</code> object. - * <code>IO.select</code> calls <code>to_io</code> 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 <code>IO.select</code> doesn't mean - * readability from <code>OpenSSL::SSL::SSLSocket</code> object. + * This means that readability notified by IO.select doesn't mean + * readability from OpenSSL::SSL::SSLSocket object. * - * The most likely situation is that <code>OpenSSL::SSL::SSLSocket</code> buffers some data. - * <code>IO.select</code> doesn't see the buffer. - * So <code>IO.select</code> can block when <code>OpenSSL::SSL::SSLSocket#readpartial</code> 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, - * <code>IO.select</code> notifies readability but - * <code>OpenSSL::SSL::SSLSocket</code> cannot decrypt a byte and - * <code>OpenSSL::SSL::SSLSocket#readpartial</code> 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 <code>OpenSSL::SSL::SSLSocket#readpartial</code> may - * invoke <code>write</code> system call and it can block. - * In such a situation, <code>OpenSSL::SSL::SSLSocket#read_nonblock</code> - * 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 <code>IO.select</code> 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 <code>IO.select</code> before <code>IO#readpartial</code> works well as usual. - * However it is not the best way to use <code>IO.select</code>. + * 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. - * <code>IO#write</code> method blocks until given whole string is written. - * So, <code>IO#write(two or more bytes)</code> can block after writability is notified by <code>IO.select</code>. - * <code>IO#write_nonblock</code> is required to avoid the blocking. + * IO#write method blocks until given whole string is written. + * So, <code>IO#write(two or more bytes)</code> can block after + * writability is notified by IO.select. IO#write_nonblock is required + * to avoid the blocking. * - * Blocking write (<code>write</code>) can be emulated using - * <code>write_nonblock</code> and <code>IO.select</code> as follows: - * IO::WaitReadable should also be rescued for SSL renegotiation in <code>OpenSSL::SSL::SSLSocket</code>. + * 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 <code>IO</code> objects that wait until ready for read - * write_array:: an array of <code>IO</code> objects that wait until ready for write - * error_array:: an array of <code>IO</code> 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 <i>arg</i> is a number, its value is passed * directly. If it is a string, it is interpreted as a binary sequence - * of bytes (<code>Array#pack</code> might be a useful way to build this - * string). On Unix platforms, see <code>fcntl(2)</code> for details. - * Not implemented on all platforms. + * of bytes (Array#pack might be a useful way to build this string). On + * Unix platforms, see <code>fcntl(2)</code> 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 <code>IO</code> objects: + * returns them as a two-element array of IO objects: * <code>[</code> <i>read_io</i>, <i>write_io</i> <code>]</code>. * * 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). <code>read</code> - * 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 (<code>"|"</code>), 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 <i>offset</i>, then returns - * <i>length</i> bytes (defaulting to the rest of the file). - * <code>binread</code> ensures the file is closed before returning. - * The open mode would be "rb:ASCII-8BIT". + * Opens the file, optionally seeks to the given <i>offset</i>, then + * returns <i>length</i> bytes (defaulting to the rest of the file). + * #binread ensures the file is closed before returning. The open mode + * would be <code>"rb:ASCII-8BIT"</code>. * * 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 <i>offset</i>, writes - * <i>string</i>, then returns the length written. - * <code>write</code> ensures the file is closed before returning. - * If <i>offset</i> is not given in write mode, the file is truncated. - * Otherwise, it is not truncated. + * <i>string</i>, then returns the length written. #write ensures the + * file is closed before returning. If <i>offset</i> 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 <code>IO.write</code> 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 (<code>"wb:ASCII-8BIT"</code>). */ static VALUE @@ -11578,9 +11565,8 @@ copy_stream_finalize(VALUE arg) * * IO.copy_stream copies <i>src</i> to <i>dst</i>. * <i>src</i> and <i>dst</i> is either a filename or an IO-like object. - * IO-like object for <i>src</i> should have <code>readpartial</code> or - * <code>read</code> method. - * IO-like object for <i>dst</i> should have <code>write</code> method. + * IO-like object for <i>src</i> should have #readpartial or #read + * method. IO-like object for <i>dst</i> 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 <code>EOFError</code> 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 <code>EOFError</code> 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 <code>each_line</code>. + * 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 <code>each_byte</code>. + * 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 <code>each_char</code>. + * 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 <code>each_codepoint</code>. + * This is a deprecated alias for #each_codepoint. */ static VALUE |