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 + + * ext/fcntl/fcntl.c: Document Fcntl constants + Sat Jan 26 12:54:40 2013 Eric Hodel * 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 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 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 - * - * = 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 set of operations and constants available depends upon specific + * operating system. Some values listed below may not be supported on your + * system. * - * The constants supported by Ruby for use with IO::fcntl are: + * See your fcntl(2) man page for complete details. * - * - 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. - * - * - F_RDLCK, F_WRLCK, F_UNLCK - types of lock for the above. - * - * 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 }