зеркало из https://github.com/github/ruby.git
[DOC] RDoc for File::Constants (#8103)
This commit is contained in:
Burdette Lamar
GitHub
Родитель
4dccb145a8
Коммит
bcc160b449
40
dir.c
40
dir.c
|
|
@ -3654,52 +3654,12 @@ Init_Dir(void)
|
|||
|
||||
rb_define_singleton_method(rb_cFile,"fnmatch", file_s_fnmatch, -1);
|
||||
rb_define_singleton_method(rb_cFile,"fnmatch?", file_s_fnmatch, -1);
|
||||
|
||||
/* Document-const: File::Constants::FNM_NOESCAPE
|
||||
*
|
||||
* Disables escapes in File.fnmatch and Dir.glob patterns
|
||||
*/
|
||||
rb_file_const("FNM_NOESCAPE", INT2FIX(FNM_NOESCAPE));
|
||||
|
||||
/* Document-const: File::Constants::FNM_PATHNAME
|
||||
*
|
||||
* Wildcards in File.fnmatch and Dir.glob patterns do not match directory
|
||||
* separators
|
||||
*/
|
||||
rb_file_const("FNM_PATHNAME", INT2FIX(FNM_PATHNAME));
|
||||
|
||||
/* Document-const: File::Constants::FNM_DOTMATCH
|
||||
*
|
||||
* The '*' wildcard matches filenames starting with "." in File.fnmatch
|
||||
* and Dir.glob patterns
|
||||
*/
|
||||
rb_file_const("FNM_DOTMATCH", INT2FIX(FNM_DOTMATCH));
|
||||
|
||||
/* Document-const: File::Constants::FNM_CASEFOLD
|
||||
*
|
||||
* Makes File.fnmatch patterns case insensitive (but not Dir.glob
|
||||
* patterns).
|
||||
*/
|
||||
rb_file_const("FNM_CASEFOLD", INT2FIX(FNM_CASEFOLD));
|
||||
|
||||
/* Document-const: File::Constants::FNM_EXTGLOB
|
||||
*
|
||||
* Allows file globbing through "{a,b}" in File.fnmatch patterns.
|
||||
*/
|
||||
rb_file_const("FNM_EXTGLOB", INT2FIX(FNM_EXTGLOB));
|
||||
|
||||
/* Document-const: File::Constants::FNM_SYSCASE
|
||||
*
|
||||
* System default case insensitiveness, equals to FNM_CASEFOLD or
|
||||
* 0.
|
||||
*/
|
||||
rb_file_const("FNM_SYSCASE", INT2FIX(FNM_SYSCASE));
|
||||
|
||||
/* Document-const: File::Constants::FNM_SHORTNAME
|
||||
*
|
||||
* Makes patterns to match short names if existing. Valid only
|
||||
* on Microsoft Windows.
|
||||
*/
|
||||
rb_file_const("FNM_SHORTNAME", INT2FIX(FNM_SHORTNAME));
|
||||
}
|
||||
|
||||
|
|
|
|||
342
file.c
342
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);
|
||||
|
|
|
|||
Загрузка…
Ссылка в новой задаче