* ext/fcntl/fcntl.c: Document Fcntl constants

git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@38949 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

2 files changed, 123 insertions, 65 deletions

diff --git a/ChangeLog b/ChangeLog
index 6e4039e0ec..e6ad354536 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,7 @@
+Sat Jan 26 13:35:56 2013  Eric Hodel  <drbrain@segment7.net>
+
+	* ext/fcntl/fcntl.c:  Document Fcntl constants
+
 Sat Jan 26 12:54:40 2013  Eric Hodel  <drbrain@segment7.net>
 
 	* hash.c (rb_env_size):  Restored documentation for ENV.size
diff --git a/ext/fcntl/fcntl.c b/ext/fcntl/fcntl.c
index b0992f30d8..311569c134 100644
--- a/ext/fcntl/fcntl.c
+++ b/ext/fcntl/fcntl.c
@@ -14,12 +14,6 @@
 
 fcntl - load the C fcntl.h defines
 
-= SYNOPSIS
-
-    require "fcntl"
-    m = s.fcntl(Fcntl::F_GETFL, 0)
-    f.fcntl(Fcntl::F_SETFL, Fcntl::O_NONBLOCK|m)
-
 = DESCRIPTION
 
 This module is just a translation of the C <fcntl.h> file.
@@ -37,151 +31,211 @@ pack up your own arguments to pass as args for locking functions, etc.
 /* Fcntl loads the constants defined in the system's <fcntl.h> C header
  * file, and used with both the fcntl(2) and open(2) POSIX system calls.
  *
- * Copyright (C) 1997-2001 Yukihiro Matsumoto
- *
- * Documented by mathew <meta@pobox.com>
- *
- * = Usage
- *
- * To perform a fcntl(2) operation, use IO::fcntl in the core classes.
+ * To perform a fcntl(2) operation, use IO::fcntl.
  *
  * To perform an open(2) operation, use IO::sysopen.
  *
- * The set of operations and constants available depends upon specific OS
- * platform. Some values listed below may not be supported on your system.
- *
- * The constants supported by Ruby for use with IO::fcntl are:
- *
- * - F_DUPFD - duplicate a close-on-exec file handle to a non-close-on-exec
- *   file handle.
- *
- * - F_GETFD - read the close-on-exec flag of a file handle.
- *
- * - F_SETFD - set the close-on-exec flag of a file handle.
- *
- * - FD_CLOEXEC - the value of the close-on-exec flag.
- *
- * - F_GETFL - get file descriptor flags.
- *
- * - F_SETFL - set file descriptor flags.
- *
- * - O_APPEND, O_NONBLOCK, etc (see below) - file descriptor flag
- *   values for the above.
- *
- * - F_GETLK - determine whether a given region of a file is locked.
- *
- * - F_SETLK - acquire a lock on a region of a file.
- *
- * - F_SETLKW - acquire a lock on a region of a file, waiting if necessary.
+ * The set of operations and constants available depends upon specific
+ * operating system.  Some values listed below may not be supported on your
+ * system.
  *
- * - F_RDLCK, F_WRLCK, F_UNLCK - types of lock for the above.
+ * See your fcntl(2) man page for complete details.
  *
- * The constants supported by Ruby for use with IO::sysopen are:
- *
- * - O_APPEND - open file in append mode.
- *
- * - O_NOCTTY - open tty without it becoming controlling tty.
- *
- * - O_CREAT - create file if it doesn't exist.
- *
- * - O_EXCL - used with O_CREAT, fail if file exists.
- *
- * - O_TRUNC - truncate file on open.
- *
- * - O_NONBLOCK / O_NDELAY - open in non-blocking mode.
- *
- * - O_RDONLY - open read-only.
- *
- * - O_WRONLY - open write-only.
- *
- * - O_RDWR - open read-write.
- *
- * - O_ACCMODE - mask to extract read/write flags.
- *
- * Example:
+ * Open /tmp/tempfile as a write-only file that is created if it doesn't
+ * exist:
  *
  *   require 'fcntl'
  *
- *   fd = IO::sysopen('/tmp/tempfile',
- *        Fcntl::O_WRONLY | Fcntl::O_EXCL | Fcntl::O_CREAT)
+ *   fd = IO.sysopen('/tmp/tempfile',
+ *                   Fcntl::O_WRONLY | Fcntl::O_EXCL | Fcntl::O_CREAT)
  *   f = IO.open(fd)
  *   f.syswrite("TEMP DATA")
  *   f.close
  *
+ * Get the flags on file +s+:
+ *
+ *   m = s.fcntl(Fcntl::F_GETFL, 0)
+ *
+ * Set the non-blocking flag on +f+ in addition to the existing flags in +m+.
+ *
+ *   f.fcntl(Fcntl::F_SETFL, Fcntl::O_NONBLOCK|m)
+ *
  */
 void
 Init_fcntl()
 {
     VALUE mFcntl = rb_define_module("Fcntl");
 #ifdef F_DUPFD
+    /* Document-const: F_DUPFD
+     *
+     * Duplicate a close-on-exec file handle to a non-close-on-exec file
+     * handle.
+     */
     rb_define_const(mFcntl, "F_DUPFD", INT2NUM(F_DUPFD));
 #endif
 #ifdef F_GETFD
+    /* Document-const: F_GETFD
+     *
+     * Read the close-on-exec flag of a file handle.
+     */
     rb_define_const(mFcntl, "F_GETFD", INT2NUM(F_GETFD));
 #endif
 #ifdef F_GETLK
+    /* Document-const: F_GETLK
+     *
+     * Determine whether a given region of a file is locked.  This uses one of
+     * the F_*LK flags.
+     */
     rb_define_const(mFcntl, "F_GETLK", INT2NUM(F_GETLK));
 #endif
 #ifdef F_SETFD
+    /* Document-const: F_SETFD
+     *
+     * Set the close-on-exec flag of a file handle.
+     */
     rb_define_const(mFcntl, "F_SETFD", INT2NUM(F_SETFD));
 #endif
 #ifdef F_GETFL
+    /* Document-const: F_GETFL
+     *
+     * Get the file descriptor flags.  This will be one or more of the O_*
+     * flags.
+     */
     rb_define_const(mFcntl, "F_GETFL", INT2NUM(F_GETFL));
 #endif
 #ifdef F_SETFL
+    /* Document-const: F_SETFL
+     *
+     * Set the file descriptor flags.  This will be one or more of the O_*
+     * flags.
+     */
     rb_define_const(mFcntl, "F_SETFL", INT2NUM(F_SETFL));
 #endif
 #ifdef F_SETLK
+    /* Document-const: F_SETLK
+     *
+     * Acquire a lock on a region of a file.  This uses one of the F_*LCK
+     * flags.
+     */
     rb_define_const(mFcntl, "F_SETLK", INT2NUM(F_SETLK));
 #endif
 #ifdef F_SETLKW
+    /* Document-const: F_SETLKW
+     *
+     * Acquire a lock on a region of a file, waiting if necessary.  This uses
+     * one of the F_*LCK flags
+     */
     rb_define_const(mFcntl, "F_SETLKW", INT2NUM(F_SETLKW));
 #endif
 #ifdef FD_CLOEXEC
+    /* Document-const: F_CLOEXEC
+     *
+     * the value of the close-on-exec flag.
+     */
     rb_define_const(mFcntl, "FD_CLOEXEC", INT2NUM(FD_CLOEXEC));
 #endif
 #ifdef F_RDLCK
+    /* Document-const: F_RDLCK
+     *
+     * Read lock for a region of a file
+     */
     rb_define_const(mFcntl, "F_RDLCK", INT2NUM(F_RDLCK));
 #endif
 #ifdef F_UNLCK
+    /* Document-const: F_UNLCK
+     *
+     * Remove lock for a region of a file
+     */
     rb_define_const(mFcntl, "F_UNLCK", INT2NUM(F_UNLCK));
 #endif
 #ifdef F_WRLCK
+    /* Document-const: F_WRLCK
+     *
+     * Write lock for a region of a file
+     */
     rb_define_const(mFcntl, "F_WRLCK", INT2NUM(F_WRLCK));
 #endif
 #ifdef O_CREAT
+    /* Document-const: O_CREAT
+     *
+     * Create the file if it doesn't exist
+     */
     rb_define_const(mFcntl, "O_CREAT", INT2NUM(O_CREAT));
 #endif
 #ifdef O_EXCL
+    /* Document-const: O_EXCL
+     *
+     * Used with O_CREAT, fail if the file exists
+     */
     rb_define_const(mFcntl, "O_EXCL", INT2NUM(O_EXCL));
 #endif
 #ifdef O_NOCTTY
+    /* Document-const: O_NOCTTY
+     *
+     * Open TTY without it becoming the controlling TTY
+     */
     rb_define_const(mFcntl, "O_NOCTTY", INT2NUM(O_NOCTTY));
 #endif
 #ifdef O_TRUNC
+    /* Document-const: O_TRUNC
+     *
+     * Truncate the file on open
+     */
     rb_define_const(mFcntl, "O_TRUNC", INT2NUM(O_TRUNC));
 #endif
 #ifdef O_APPEND
+    /* Document-const: O_APPEND
+     *
+     * Open the file in append mode
+     */
     rb_define_const(mFcntl, "O_APPEND", INT2NUM(O_APPEND));
 #endif
 #ifdef O_NONBLOCK
+    /* Document-const: O_NONBLOCK
+     *
+     * Open the file in non-blocking mode
+     */
     rb_define_const(mFcntl, "O_NONBLOCK", INT2NUM(O_NONBLOCK));
 #endif
 #ifdef O_NDELAY
+    /* Document-const: O_NDELAY
+     *
+     * Open the file in non-blocking mode
+     */
     rb_define_const(mFcntl, "O_NDELAY", INT2NUM(O_NDELAY));
 #endif
 #ifdef O_RDONLY
+    /* Document-const: O_RDONLY
+     *
+     * Open the file in read-only mode
+     */
     rb_define_const(mFcntl, "O_RDONLY", INT2NUM(O_RDONLY));
 #endif
 #ifdef O_RDWR
+    /* Document-const: O_RDWR
+     *
+     * Open the file in read-write mode
+     */
     rb_define_const(mFcntl, "O_RDWR", INT2NUM(O_RDWR));
 #endif
 #ifdef O_WRONLY
+    /* Document-const: O_WRONLY
+     *
+     * Open the file in write-only mode.
+     */
     rb_define_const(mFcntl, "O_WRONLY", INT2NUM(O_WRONLY));
 #endif
 #ifdef O_ACCMODE
+    /* Document-const: O_ACCMODE
+     *
+     * Mask to extract the read/write flags
+     */
     rb_define_const(mFcntl, "O_ACCMODE", INT2FIX(O_ACCMODE));
 #else
+    /* Document-const: O_ACCMODE
+     *
+     * Mask to extract the read/write flags
+     */
     rb_define_const(mFcntl, "O_ACCMODE", INT2FIX(O_RDONLY | O_WRONLY | O_RDWR));
 #endif
 }