From patchwork Thu Oct 16 08:37:58 2014 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Rical Jasan X-Patchwork-Id: 400209 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Received: from sourceware.org (server1.sourceware.org [209.132.180.131]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ozlabs.org (Postfix) with ESMTPS id DB371140085 for ; Thu, 16 Oct 2014 19:37:32 +1100 (AEDT) DomainKey-Signature: a=rsa-sha1; c=nofws; d=sourceware.org; h=list-id :list-unsubscribe:list-subscribe:list-archive:list-post :list-help:sender:message-id:date:from:mime-version:to:subject :content-type; q=dns; s=default; b=tbGx0taNlP2XrtP7gZM8+T07sdHCd L2F7a7kmRKlpCI+++XSb6l8yKJPH186rNZJnFm8NSgLEC9RsD9Kk4cu/rwbPaIN3 5amHWSTqJm59cbNWvZKCGBFOQw/xhJ6yxJgNIBDGnxJCIGbVj5FYilygUJif3XNo m4L98zOWFEfdj8= DKIM-Signature: v=1; a=rsa-sha1; c=relaxed; d=sourceware.org; h=list-id :list-unsubscribe:list-subscribe:list-archive:list-post :list-help:sender:message-id:date:from:mime-version:to:subject :content-type; s=default; bh=O/VeabUdEGCBkJcgNqyT5uBn8gE=; b=TJI mRXN9ysMIU0JG86R2G823h5r9SvZf9oXx9C+DgOrxolABwwT/khjNpkPrzO5EvWs GaqZxnkCcS6XRehKcQ/dEDs8uS8F33F/ddR2OztmOHnnCW2QiPUHRsIejgkA+Mf2 Pl+8zvTEZ1h4cTThLTCYpQzoS56ZQb6tk0z3a0mo= Received: (qmail 27705 invoked by alias); 16 Oct 2014 08:37:25 -0000 Mailing-List: contact libc-alpha-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Unsubscribe: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: libc-alpha-owner@sourceware.org Delivered-To: mailing list libc-alpha@sourceware.org Received: (qmail 27694 invoked by uid 89); 16 Oct 2014 08:37:23 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=-0.9 required=5.0 tests=AWL, BAYES_00, SPF_PASS, T_RP_MATCHES_RCVD autolearn=ham version=3.3.2 X-HELO: mail.pacific.net Message-ID: <543F83E6.9010803@pacific.net> Date: Thu, 16 Oct 2014 01:37:58 -0700 From: ricaljasan User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:31.0) Gecko/20100101 Thunderbird/31.1.2 MIME-Version: 1.0 To: libc-alpha@sourceware.org Subject: [PATCH] Grammatical edits to the manual's introduction. X-Null-Tag: 5635f34f2596993b8a2ec9e78acd3626 Addresses issues with grammar in the Introduction chapter of the manual for the sake of both clarity and consistency with the rest of the manual. * manual/creature.texi: Edit grammar for clarity and consistency. * manual/intro.texi: Likewise. 2014-10-11 Rical Jasan * manual/creature.texi (Creature Nest Macros): Edit grammar for clarity and consistency. * manual/intro.text (Introduction): Likewise. diff --git a/manual/creature.texi b/manual/creature.texi index 3c68616..adf171a 100644 --- a/manual/creature.texi +++ b/manual/creature.texi @@ -23,7 +23,7 @@ This system exists to allow the library to conform to multiple standards. Although the different standards are often described as supersets of each other, they are usually incompatible because larger standards require functions with names that smaller ones reserve to the user program. This -is not mere pedantry --- it has been a problem in practice. For instance, +is not mere pedantry---it has been a problem in practice. For instance, some non-GNU programs define functions named @code{getline} that have nothing to do with this library's @code{getline}. They would not be compilable if all features were enabled indiscriminately. @@ -98,7 +98,7 @@ Single Unix Specification, @w{version 2}. @comment (NONE) @comment X/Open @defvr Macro _LARGEFILE_SOURCE -If this macro is defined some extra functions are available which +If this macro is defined, some extra functions are available which rectify a few shortcomings in all previous standards. Specifically, the functions @code{fseeko} and @code{ftello} are available. Without these functions the difference between the @w{ISO C} interface @@ -143,7 +143,7 @@ types like @code{off_t} have a size of @w{32 bits} on @w{32 bit} systems. If the macro is defined to the value @code{64}, the large file interface -replaces the old interface. I.e., the functions are not made available +replaces the old interface---i.e., the functions are not made available under different names (as they are with @code{_LARGEFILE64_SOURCE}). Instead the old function names now reference the new functions, e.g., a call to @code{fseeko} now indeed calls @code{fseeko64}. diff --git a/manual/intro.texi b/manual/intro.texi index a1708ef..d68d4cd 100644 --- a/manual/intro.texi +++ b/manual/intro.texi @@ -22,8 +22,8 @@ portability. @menu * Getting Started:: What this manual is for and how to use it. -* Standards and Portability:: Standards and sources upon which the GNU - C library is based. +* Standards and Portability:: Standards and sources upon which + @theglibc{} is based. * Using the Library:: Some practical uses for the library. * Roadmap to the Manual:: Overview of the remaining chapters in this manual. @@ -66,7 +66,7 @@ is based upon. These sources include the @w{ISO C} and POSIX standards, and the System V and Berkeley Unix implementations. The primary focus of this manual is to tell you how to make effective -use of the @glibcadj{} facilities. But if you are concerned about +use of the @glibcadj{} facilities. If you are concerned about making your programs compatible with these standards, or portable to operating systems other than GNU, this can affect how you use the library. This section gives you an overview of these standards, so that @@ -185,14 +185,14 @@ pattern matching facilities (@pxref{Pattern Matching}). @cindex POSIX Safety Concepts This manual documents various safety properties of @glibcadj{} -functions, in lines that follow their prototypes and look like: +functions in lines that follow their prototypes and look like: @indent @sampsafety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} The properties are assessed according to the criteria set forth in the -POSIX standard for such safety contexts as Thread-, Async-Signal- and -Async-Cancel- -Safety. Intuitive definitions of these properties, +POSIX standard for such safety contexts as Thread-, Async-Signal-, and +Async-Cancel-Safe. Intuitive definitions of these properties, attempting to capture the meaning of the standard definitions, follow. @itemize @bullet @@ -240,7 +240,7 @@ save their original values, and restore them before returning. @cindex AC-Safe @cindex Async-Cancel-Safe @code{AC-Safe} or Async-Cancel-Safe functions are safe to call when -asynchronous cancellation is enabled. AC in AC-Safe stands for +asynchronous cancellation is enabled. AC, in AC-Safe, stands for Asynchronous Cancellation. The POSIX standard defines only three functions to be AC-Safe, namely @@ -265,7 +265,7 @@ the environment encountered is internally inconsistent. @cindex Async-Signal-Unsafe @cindex AC-Unsafe @cindex Async-Cancel-Unsafe -@code{MT-Unsafe}, @code{AS-Unsafe}, @code{AC-Unsafe} functions are not +@code{MT-Unsafe}, @code{AS-Unsafe}, and @code{AC-Unsafe} functions are not safe to call within the safety contexts described above. Calling them within such contexts invokes undefined behavior. @@ -551,7 +551,7 @@ those that perform implicit locking on @code{FILE} streams by default will not, even though the implicit locking may be disabled on a per-stream basis. -In either case, we will not regard as MT-Unsafe functions that may +In either case, we will not regard functions as MT-Unsafe that may access user-supplied objects in unsafe ways should users fail to ensure the accesses are well defined. The notion prevails that users are expected to safeguard against data races any user-supplied objects that @@ -629,7 +629,7 @@ use in asynchronous signals remains undefined. @item @code{sig} @cindex sig -Functions marked with @code{sig} as a MT-Safety issue (that implies an +Functions marked with @code{sig} as an MT-Safety issue (that implies an identical AS-Safety issue, omitted for brevity) may temporarily install a signal handler for internal purposes, which may interfere with other uses of the signal, identified after a colon. @@ -840,14 +840,14 @@ threads or within asynchronous signal or cancellation handlers. This is not enough of a reason to mark so-marked functions as MT- or AS-Unsafe, but when this behavior is optional (e.g., @code{nftw} with @code{FTW_CHDIR}), avoiding the option may be a good alternative to -using full pathnames or file descriptor-relative (e.g. @code{openat}) +using full pathnames or file descriptor-relative (e.g., @code{openat}) system calls. @item @code{!posix} @cindex !posix -This remark, as an MT-, AS- or AC-Safety note to a function, indicates +This remark, as an MT-, AS-, or AC-Safety note to a function, indicates the safety status of the function is known to differ from the specified status in the POSIX standard. For example, POSIX does not require a function to be Safe, but our implementation is, or vice-versa. @@ -861,16 +861,16 @@ the corresponding functions. @cindex :identifier Annotations may sometimes be followed by identifiers, intended to group -several functions that e.g. access the data structures in an unsafe way, -as in @code{race} and @code{const}, or to provide more specific -information, such as naming a signal in a function marked with +several functions that, for example, access the data structures in an +unsafe way, as in @code{race} and @code{const}, or to provide more +specific information, such as naming a signal in a function marked with @code{sig}. It is envisioned that it may be applied to @code{lock} and @code{corrupt} as well in the future. In most cases, the identifier will name a set of functions, but it may name global objects or function arguments, or identifiable properties or logical components associated with them, with a notation such as -e.g. @code{:buf(arg)} to denote a buffer associated with the argument +@code{:buf(arg)} to denote a buffer associated with the argument @var{arg}, or @code{:tcattr(fd)} to denote the terminal attributes of a file descriptor @var{fd}. @@ -884,8 +884,8 @@ context. @cindex /condition Some safety annotations may be conditional, in that they only apply if a -boolean expression involving arguments, global variables or even the -underlying kernel evaluates evaluates to true. Such conditions as +boolean expression involving arguments, global variables, or even the +underlying kernel evaluates to true. Such conditions as @code{/hurd} or @code{/!linux!bsd} indicate the preceding marker only applies when the underlying kernel is the HURD, or when it is neither Linux nor a BSD kernel, respectively. @code{/!ps} and @@ -958,7 +958,7 @@ The additions on top of POSIX are mainly derived from functionality available in @w{System V} and BSD systems. Some of the really bad mistakes in @w{System V} systems were corrected, though. Since fulfilling the XPG standard with the Unix extensions is a -precondition for getting the Unix brand chances are good that the +precondition for getting the Unix brand, chances are good that the functionality is available on commercial systems. @@ -999,7 +999,7 @@ variable or says what a function does.) In order to use the facilities in @theglibc{}, you should be sure that your program source files include the appropriate header files. -This is so that the compiler has declarations of these facilities +This is so the compiler has declarations of these facilities available and can correctly process references to them. Once your program has been compiled, the linker resolves these references to the actual definitions provided in the archive file. @@ -1176,11 +1176,11 @@ to treat these as built-in parts of the language. In addition to the names documented in this manual, reserved names include all external identifiers (global functions and variables) that -begin with an underscore (@samp{_}) and all identifiers regardless of -use that begin with either two underscores or an underscore followed by -a capital letter are reserved names. This is so that the library and -header files can define functions, variables, and macros for internal -purposes without risk of conflict with names in user programs. +begin with an underscore (@samp{_}) and all identifiers that begin +with either two underscores or an underscore followed by a capital +letter. This is so the library and header files can define functions, +variables, and macros for internal purposes without risk of conflict +with names in user programs. Some additional classes of identifier names are reserved for future extensions to the C language or the POSIX.1 environment. While using these @@ -1228,7 +1228,7 @@ Names that end with @samp{_t} are reserved for additional type names. @end itemize In addition, some individual header files reserve names beyond -those that they actually define. You only need to worry about these +those they actually define. You only need to worry about these restrictions if your program includes that particular header file. @itemize @bullet