From patchwork Thu Nov 10 18:00:17 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Sandra Loosemore X-Patchwork-Id: 81722 Delivered-To: patch@linaro.org Received: by 10.182.1.168 with SMTP id 8csp1030640obn; Thu, 10 Nov 2016 10:00:46 -0800 (PST) X-Received: by 10.36.60.208 with SMTP id m199mr837574ita.15.1478800846862; Thu, 10 Nov 2016 10:00:46 -0800 (PST) Return-Path: Received: from sourceware.org (server1.sourceware.org. [209.132.180.131]) by mx.google.com with ESMTPS id sn2si5102789pac.336.2016.11.10.10.00.46 for (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Thu, 10 Nov 2016 10:00:46 -0800 (PST) Received-SPF: pass (google.com: domain of gcc-patches-return-441004-patch=linaro.org@gcc.gnu.org designates 209.132.180.131 as permitted sender) client-ip=209.132.180.131; Authentication-Results: mx.google.com; dkim=pass header.i=@gcc.gnu.org; spf=pass (google.com: domain of gcc-patches-return-441004-patch=linaro.org@gcc.gnu.org designates 209.132.180.131 as permitted sender) smtp.mailfrom=gcc-patches-return-441004-patch=linaro.org@gcc.gnu.org DomainKey-Signature: a=rsa-sha1; c=nofws; d=gcc.gnu.org; h=list-id :list-unsubscribe:list-archive:list-post:list-help:sender:to:cc :from:subject:message-id:date:mime-version:content-type; q=dns; s=default; b=lsCN9NDl0MNdyl6xlinXSY+4k1isBlyyBeNs5jtriAIGVa1Y+P smSOB/JDjZ8oUdsSAsk3En5EVc+lmbJW3/DbE3FN7KvqJWakCLVw2yyzcH6PwtM+ fgphmffVjtwyz/+v8373jjWQ34AYbaH2GZ4K8VVJDjeJP5GJPhQ/v9JR0= DKIM-Signature: v=1; a=rsa-sha1; c=relaxed; d=gcc.gnu.org; h=list-id :list-unsubscribe:list-archive:list-post:list-help:sender:to:cc :from:subject:message-id:date:mime-version:content-type; s= default; bh=9eVCW/oG4yIvknuQ73DwH3ugvDk=; b=jv5b62UDZoQRoHN1pbtr vVI/QKHaWCYcqp3BDRnKTZJ0Vk0LLe52iQ6FnSMYj7me0p0S0ZJRRchzHJToLdWW SXFXlbWiINGYshw3vYsRFQWQrpy+BYUCbVzRq5xxW3ei8uTRZ2SAYyU2NwXG8ShU XWqF0UrEiWBVE89uGyHQ0pg= Received: (qmail 104727 invoked by alias); 10 Nov 2016 18:00:34 -0000 Mailing-List: contact gcc-patches-help@gcc.gnu.org; run by ezmlm Precedence: bulk List-Id: List-Unsubscribe: List-Archive: List-Post: List-Help: Sender: gcc-patches-owner@gcc.gnu.org Delivered-To: mailing list gcc-patches@gcc.gnu.org Received: (qmail 104707 invoked by uid 89); 10 Nov 2016 18:00:33 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=-1.8 required=5.0 tests=AWL, BAYES_00, RCVD_IN_DNSWL_NONE, SPF_PASS, URIBL_RED autolearn=ham version=3.3.2 spammy=Gen, wish X-HELO: relay1.mentorg.com Received: from relay1.mentorg.com (HELO relay1.mentorg.com) (192.94.38.131) by sourceware.org (qpsmtpd/0.93/v0.84-503-g423c35a) with ESMTP; Thu, 10 Nov 2016 18:00:23 +0000 Received: from svr-orw-mbx-03.mgc.mentorg.com ([147.34.90.203]) by relay1.mentorg.com with esmtp id 1c4te9-0005dB-Q8 from Sandra_Loosemore@mentor.com for gcc-patches@gcc.gnu.org; Thu, 10 Nov 2016 10:00:21 -0800 Received: from [127.0.0.1] (147.34.91.1) by svr-orw-mbx-03.mgc.mentorg.com (147.34.90.203) with Microsoft SMTP Server (TLS) id 15.0.1210.3; Thu, 10 Nov 2016 10:00:19 -0800 To: "gcc-patches@gcc.gnu.org" CC: Joseph Myers From: Sandra Loosemore Subject: [patch, doc] PR 37998 -- Unclear documentation of -fno-common Message-ID: <5824B5B1.8000105@codesourcery.com> Date: Thu, 10 Nov 2016 11:00:17 -0700 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:38.0) Gecko/20100101 Thunderbird/38.5.1 MIME-Version: 1.0 X-ClientProxiedBy: svr-orw-mbx-02.mgc.mentorg.com (147.34.90.202) To svr-orw-mbx-03.mgc.mentorg.com (147.34.90.203) This patch is for a long-standing issue with the way -fno-common is documented. The specific bug report was about an ambiguous use of the word "This", but as I looked more at the way this option was described, I realized the whole thing was needlessly confusing because it didn't use the correct terminology -- the current text tries to use "declaration" to describe what the C standard calls a "tentative definition". Joseph, can you look this over with your language-lawyer hat on, before I commit it? I'm pretty sure I understand what this option does, but I want to be sure I'm explaining it correctly now. -Sandra Index: gcc/doc/invoke.texi =================================================================== --- gcc/doc/invoke.texi (revision 241974) +++ gcc/doc/invoke.texi (working copy) @@ -11953,25 +11953,32 @@ Use it to conform to a non-default appli @item -fno-common @opindex fno-common -In C code, controls the placement of uninitialized global variables. -Unix C compilers have traditionally permitted multiple definitions of -such variables in different compilation units by placing the variables -in a common block. -This is the behavior specified by @option{-fcommon}, and is the default -for GCC on most targets. -On the other hand, this behavior is not required by ISO C, and on some -targets may carry a speed or code size penalty on variable references. -The @option{-fno-common} option specifies that the compiler should place -uninitialized global variables in the data section of the object file, -rather than generating them as common blocks. -This has the effect that if the same variable is declared -(without @code{extern}) in two different compilations, -you get a multiple-definition error when you link them. -In this case, you must compile with @option{-fcommon} instead. +@cindex tentative definitions +In C code, this option controls the placement of global variables +defined without an initializer, known as @dfn{tentative definitions} +in the C standard. Tentative definitions are distinct from declarations +of a variable with the @code{extern} keyword, which do not allocate storage. + +Unix C compilers have traditionally allocated storage for +uninitialized global variables in a common block. This allows the +linker to resolve all tentative definitions of the same variable +in different compilation units to the same object, or to a non-tentative +definition. +This is the behavior specified by @option{-fcommon}, and is the default for +GCC on most targets. +On the other hand, this behavior is not required by ISO +C, and on some targets may carry a speed or code size penalty on +variable references. + +The @option{-fno-common} option specifies that the compiler should instead +place uninitialized global variables in the data section of the object file. +This inhibits the merging of tentative definitions by the linker so +you get a multiple-definition error if the same +variable is defined in more than one compilation unit. Compiling with @option{-fno-common} is useful on targets for which it provides better performance, or if you wish to verify that the program will work on other systems that always treat uninitialized -variable declarations this way. +variable definitions this way. @item -fno-ident @opindex fno-ident