[DOC] RDoc for File::Constants (#8103)

1 files changed, 311 insertions, 31 deletions

diff --git a/file.c b/file.c
index 0966d5bb23..fadee48e9b 100644
--- a/file.c
+++ b/file.c
@@ -7431,93 +7431,373 @@ Init_File(void)
     /*
      * Document-module: File::Constants
      *
-     * File::Constants provides file-related constants.  All possible
-     * file constants are listed in the documentation but they may not all
-     * be present on your platform.
+     * \Module +File::Constants+ defines file-related constants.
      *
-     * If the underlying platform doesn't define a constant the corresponding
-     * Ruby constant is not defined.
+     * There are two families of constants here:
+     *
+     * - Those having to do with {file access}[rdoc-ref:File::Constants@File+Access].
+     * - Those having to do with {file globbing}[rdoc-ref:File::Constants@File+Globbing].
+     *
+     * \File constants defined for the local process may be retrieved
+     * with method File::Constants.constants:
+     *
+     *   File::Constants.constants.take(5)
+     *   # => [:RDONLY, :WRONLY, :RDWR, :APPEND, :CREAT]
+     *
+     * == \File Access
+     *
+     * \File-access constants may be used with optional argument +mode+ in calls
+     * to the following methods:
+     *
+     * - File.new.
+     * - File.open.
+     * - IO.for_fd.
+     * - IO.new.
+     * - IO.open.
+     * - IO.popen.
+     * - IO.reopen.
+     * - IO.sysopen.
+     * - StringIO.new.
+     * - StringIO.open.
+     * - StringIO#reopen.
+     *
+     * === Read/Write Access
+     *
+     * Read-write access for a stream
+     * may be specified by a file-access constant.
+     *
+     * The constant may be specified as part of a bitwise OR of other such constants.
+     *
+     * Any combination of the constants in this section may be specified.
+     *
+     * ==== File::RDONLY
+     *
+     * Flag File::RDONLY specifies the the stream should be opened for reading only:
+     *
+     *   filepath = '/tmp/t.tmp'
+     *   f = File.new(filepath, File::RDONLY)
+     *   f.write('Foo') # Raises IOError (not opened for writing).
+     *
+     * ==== File::WRONLY
+     *
+     * Flag File::WRONLY specifies that the stream should be opened for writing only:
+     *
+     *   f = File.new(filepath, File::WRONLY)
+     *   f.read # Raises IOError (not opened for reading).
+     *
+     * ==== File::RDWR
+     *
+     * Flag File::RDWR specifies that the stream should be opened
+     * for both reading and writing:
+     *
+     *   f = File.new(filepath, File::RDWR)
+     *   f.write('Foo') # => 3
+     *   f.rewind       # => 0
+     *   f.read         # => "Foo"
+     *
+     * === \File Positioning
+     *
+     * ==== File::APPEND
+     *
+     * Flag File::APPEND specifies that the stream should be opened
+     * in append mode.
+     *
+     * Before each write operation, the position is set to end-of-stream.
+     * The modification of the position and the following write operation
+     * are performed as a single atomic step.
+     *
+     * ==== File::TRUNC
+     *
+     * Flag File::TRUNC specifies that the stream should be truncated
+     * at its beginning.
+     * If the file exists and is successfully opened for writing,
+     * it is to be truncated to position zero;
+     * its ctime and mtime are updated.
+     *
+     * There is no effect on a FIFO special file or a terminal device.
+     * The effect on other file types is implementation-defined.
+     * The result of using File::TRUNC with File::RDONLY is undefined.
+     *
+     * === Creating and Preserving
+     *
+     * ==== File::CREAT
+     *
+     * Flag File::CREAT specifies that the stream should be created
+     * if it does not already exist.
+     *
+     * If the file exists:
+     *
+     *   - Raise an exception if File::EXCL is also specified.
+     *   - Otherwise, do nothing.
+     *
+     * If the file does not exist, then it is created.
+     * Upon successful completion, the atime, ctime, and mtime of the file are updated,
+     * and the ctime and mtime of the parent directory are updated.
+     *
+     * ==== File::EXCL
+     *
+     * Flag File::EXCL specifies that the stream should not already exist;
+     * If flags File::CREAT and File::EXCL are both specified
+     * and the stream already exists, an exception is raised.
+     *
+     * The check for the existence and creation of the file is performed as an
+     * atomic operation.
+     *
+     * If both File::EXCL and File::CREAT are specified and the path names a symbolic link,
+     * an exception is raised regardless of the contents of the symbolic link.
+     *
+     * If File::EXCL is specified and File::CREAT is not specified,
+     * the result is undefined.
+     *
+     * === POSIX \File \Constants
+     *
+     * Some file-access constants are defined only on POSIX-compliant systems;
+     * those are:
+     *
+     * - File::SYNC.
+     * - File::DSYNC.
+     * - File::RSYNC.
+     * - File::DIRECT.
+     * - File::NOATIME.
+     * - File::NOCTTY.
+     * - File::NOFOLLOW.
+     * - File::TMPFILE.
+     *
+     * ==== File::SYNC, File::RSYNC, and File::DSYNC
+     *
+     * Flag File::SYNC, File::RSYNC, or File::DSYNC
+     * specifies synchronization of I/O operations with the underlying file system.
+     *
+     * These flags are valid only for POSIX-compliant systems.
+     *
+     * - File::SYNC specifies that all write operations (both data and metadata)
+     *   are immediately to be flushed to the underlying storage device.
+     *   This means that the data is written to the storage device,
+     *   and the file's metadata (e.g., file size, timestamps, permissions)
+     *   are also synchronized.
+     *   This guarantees that data is safely stored on the storage medium
+     *   before returning control to the calling program.
+     *   This flag can have a significant impact on performance
+     *   since it requires synchronous writes, which can be slower
+     *   compared to asynchronous writes.
+     *
+     * - File::RSYNC specifies that any read operations on the file will not return
+     *   until all outstanding write operations
+     *   (those that have been issued but not completed) are also synchronized.
+     *   This is useful when you want to read the most up-to-date data,
+     *   which may still be in the process of being written.
+     *
+     * - File::DSYNC specifies that all _data_ write operations
+     *   are immediately to be flushed to the underlying storage device;
+     *   this differs from File::SYNC, which requires that _metadata_
+     *   also be synchronized.
+     *
+     * Note that the behavior of these flags may vary slightly
+     * depending on the operating system and filesystem being used.
+     * Additionally, using these flags can have an impact on performance
+     * due to the synchronous nature of the I/O operations,
+     * so they should be used judiciously,
+     * especially in performance-critical applications.
+     *
+     * ==== File::NOCTTY
+     *
+     * Flag File::NOCTTY specifies that if the stream is a terminal device,
+     * that device does not become the controlling terminal for the process.
+     *
+     * Defined only for POSIX-compliant systems.
+     *
+     * ==== File::DIRECT
+     *
+     * Flag File::DIRECT requests that cache effects of the I/O to and from the stream
+     * be minimized.
+     *
+     * Defined only for POSIX-compliant systems.
+     *
+     * ==== File::NOATIME
+     *
+     * Flag File::NOATIME specifies that act of opening the stream
+     * should not modify its access time (atime).
+     *
+     * Defined only for POSIX-compliant systems.
+     *
+     * ==== File::NOFOLLOW
+     *
+     * Flag File::NOFOLLOW specifies that if path is a symbolic link,
+     * it should not be followed.
+     *
+     * Defined only for POSIX-compliant systems.
+     *
+     * ==== File::TMPFILE
+     *
+     * Flag File::TMPFILE specifies that the opened stream
+     * should be a new temporary file.
+     *
+     * Defined only for POSIX-compliant systems.
+     *
+     * === Other File-Access \Constants
+     *
+     * ==== File::NONBLOCK
+     *
+     * When possible, the file is opened in nonblocking mode.
+     * Neither the open operation nor any subsequent I/O operations on
+     * the file will cause the calling process to wait.
+     *
+     * ==== File::BINARY
+     *
+     * Flag File::BINARY specifies that the stream is to be accessed in binary mode.
+     *
+     * ==== File::SHARE_DELETE (Windows Only)
+     *
+     * Flag File::SHARE_DELETE enables other processes to open the stream
+     * with delete access.
+     *
+     * If the stream is opened for (local) delete access without File::SHARE_DELETE,
+     * and another process attempts to open it with delete access,
+     * the attempt fails and the stream is not opened for that process.
+     *
+     * == Locking
+     *
+     * Four file constants relate to stream locking;
+     * see File#flock:
+     *
+     * ==== File::LOCK_EX
+     *
+     * Flag File::LOCK_EX specifies an exclusive lock;
+     * only one process a a time may lock the stream.
+     *
+     * ==== File::LOCK_NB
+     *
+     * Flag File::LOCK_NB specifies non-blocking locking for the stream;
+     * may be combined with File::LOCK_EX or File::LOCK_SH.
+     *
+     * ==== File::LOCK_SH
+     *
+     * Flag File::LOCK_SH specifies that multiple processes may lock
+     * the stream at the same time.
+     *
+     * ==== File::LOCK_UN
+     *
+     * Flag File::LOCK_UN specifies that the stream is not to be locked.
+     *
+     * == Filename Globbing \Constants (File::FNM_*)
+     *
+     * Filename-globbing constants may be used with optional argument +flags+
+     * in calls to the following methods:
+     *
+     * - Dir.glob.
+     * - File.fnmatch.
+     * - Pathname#fnmatch.
+     * - Pathname.glob.
+     * - Pathname#glob.
+     *
+     * The constants are:
+     *
+     * ==== File::FNM_CASEFOLD
+     *
+     * Flag File::FNM_CASEFOLD makes patterns case insensitive
+     * for File.fnmatch (but not Dir.glob).
+     *
+     * ==== File::FNM_DOTMATCH
+     *
+     * Flag File::FNM_DOTMATCH makes the <tt>'*'</tt> pattern
+     * match a filename starting with <tt>'.'</tt>.
+     *
+     * ==== File::FNM_EXTGLOB
+     *
+     * Flag File::FNM_EXTGLOB enables pattern <tt>'{_a_,_b_}'</tt>,
+     * which matches pattern '_a_' and pattern '_b_';
+     * behaves like
+     * a {regexp union}[https://docs.ruby-lang.org/en/master/Regexp.html#method-c-union]
+     * (e.g., <tt>'(?:_a_|_b_)'</tt>):
+     *
+     *   pattern = '{LEGAL,BSDL}'
+     *   Dir.glob(pattern)      # => ["LEGAL", "BSDL"]
+     *   Pathname.glob(pattern) # => [#<Pathname:LEGAL>, #<Pathname:BSDL>]
+     *   pathname.glob(pattern) # => [#<Pathname:LEGAL>, #<Pathname:BSDL>]
+     *
+     * ==== File::FNM_NOESCAPE
+     *
+     * Flag File::FNM_NOESCAPE disables <tt>'\'</tt> escaping.
+     *
+     * ==== File::FNM_PATHNAME
+     *
+     * Flag File::FNM_PATHNAME specifies that patterns <tt>'*'</tt> and <tt>'?'</tt>
+     * do not match the directory separator
+     * (the value of constant File::SEPARATOR).
+     *
+     * ==== File::FNM_SHORTNAME (Windows Only)
+     *
+     * Flag File::FNM_SHORTNAME Allows patterns to match short names if they exist.
+     *
+     * ==== File::FNM_SYSCASE
+     *
+     * Flag File::FNM_SYSCASE specifies that case sensitivity
+     * is the same as in the underlying operating system;
+     * effective for File.fnmatch, but not Dir.glob.
+     *
+     * == Other \Constants
+     *
+     * ==== File::NULL
+     *
+     * Flag File::NULL contains the string value of the null device:
+     *
+     * - On a Unix-like OS, <tt>'/dev/null'</tt>.
+     * - On Windows, <tt>'NUL'</tt>.
      *
-     * Your platform documentations (e.g. man open(2)) may describe more
-     * detailed information.
      */
     rb_mFConst = rb_define_module_under(rb_cFile, "Constants");
     rb_include_module(rb_cIO, rb_mFConst);
-
-    /* open for reading only */
     rb_define_const(rb_mFConst, "RDONLY", INT2FIX(O_RDONLY));
-    /* open for writing only */
     rb_define_const(rb_mFConst, "WRONLY", INT2FIX(O_WRONLY));
-    /* open for reading and writing */
     rb_define_const(rb_mFConst, "RDWR", INT2FIX(O_RDWR));
-    /* append on each write */
     rb_define_const(rb_mFConst, "APPEND", INT2FIX(O_APPEND));
-    /* create file if it does not exist */
     rb_define_const(rb_mFConst, "CREAT", INT2FIX(O_CREAT));
-    /* error if CREAT and the file exists */
     rb_define_const(rb_mFConst, "EXCL", INT2FIX(O_EXCL));
 #if defined(O_NDELAY) || defined(O_NONBLOCK)
 # ifndef O_NONBLOCK
 #   define O_NONBLOCK O_NDELAY
 # endif
-    /* do not block on open or for data to become available */
     rb_define_const(rb_mFConst, "NONBLOCK", INT2FIX(O_NONBLOCK));
 #endif
-    /* truncate size to 0 */
     rb_define_const(rb_mFConst, "TRUNC", INT2FIX(O_TRUNC));
 #ifdef O_NOCTTY
-    /* not to make opened IO the controlling terminal device */
     rb_define_const(rb_mFConst, "NOCTTY", INT2FIX(O_NOCTTY));
 #endif
 #ifndef O_BINARY
 # define  O_BINARY 0
 #endif
-    /* disable line code conversion */
     rb_define_const(rb_mFConst, "BINARY", INT2FIX(O_BINARY));
 #ifndef O_SHARE_DELETE
 # define O_SHARE_DELETE 0
 #endif
-    /* can delete opened file */
     rb_define_const(rb_mFConst, "SHARE_DELETE", INT2FIX(O_SHARE_DELETE));
 #ifdef O_SYNC
-    /* any write operation perform synchronously */
     rb_define_const(rb_mFConst, "SYNC", INT2FIX(O_SYNC));
 #endif
 #ifdef O_DSYNC
-    /* any write operation perform synchronously except some meta data */
     rb_define_const(rb_mFConst, "DSYNC", INT2FIX(O_DSYNC));
 #endif
 #ifdef O_RSYNC
-    /* any read operation perform synchronously. used with SYNC or DSYNC. */
     rb_define_const(rb_mFConst, "RSYNC", INT2FIX(O_RSYNC));
 #endif
 #ifdef O_NOFOLLOW
-    /* do not follow symlinks */
     rb_define_const(rb_mFConst, "NOFOLLOW", INT2FIX(O_NOFOLLOW)); /* FreeBSD, Linux */
 #endif
 #ifdef O_NOATIME
-    /* do not change atime */
     rb_define_const(rb_mFConst, "NOATIME", INT2FIX(O_NOATIME)); /* Linux */
 #endif
 #ifdef O_DIRECT
-    /*  Try to minimize cache effects of the I/O to and from this file. */
     rb_define_const(rb_mFConst, "DIRECT", INT2FIX(O_DIRECT));
 #endif
 #ifdef O_TMPFILE
-    /* Create an unnamed temporary file */
     rb_define_const(rb_mFConst, "TMPFILE", INT2FIX(O_TMPFILE));
 #endif
 
-    /* shared lock. see File#flock */
     rb_define_const(rb_mFConst, "LOCK_SH", INT2FIX(LOCK_SH));
-    /* exclusive lock. see File#flock */
     rb_define_const(rb_mFConst, "LOCK_EX", INT2FIX(LOCK_EX));
-    /* unlock. see File#flock */
     rb_define_const(rb_mFConst, "LOCK_UN", INT2FIX(LOCK_UN));
-    /* non-blocking lock. used with LOCK_SH or LOCK_EX. see File#flock  */
     rb_define_const(rb_mFConst, "LOCK_NB", INT2FIX(LOCK_NB));
 
-    /* Name of the null device */
     rb_define_const(rb_mFConst, "NULL", rb_fstring_cstr(ruby_null_device));
 
     rb_define_global_function("test", rb_f_test, -1);