From patchwork Wed Mar 9 23:16:18 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Juan Manuel Torres Palma X-Patchwork-Id: 11295 Received: (qmail 51208 invoked by alias); 9 Mar 2016 23:16:42 -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 51169 invoked by uid 89); 9 Mar 2016 23:16:40 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=0.1 required=5.0 tests=BAYES_50, FREEMAIL_FROM, RCVD_IN_DNSWL_LOW, SPF_PASS autolearn=ham version=3.3.2 spammy=2016-03-10, 20160310, cancel, oriented X-HELO: mail-wm0-f65.google.com X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20130820; h=x-gm-message-state:date:from:to:cc:subject:message-id:mime-version :content-disposition:user-agent; bh=jwmppZWVwBE4H4aiL29yULd4jnG8QJk2EuNwCxIv/6E=; b=IxIb/g9fntjIyZ+soqkFZ8uBBFOo4LBAx1sMIYZJFc+T552c2p9iSmof/sb4VGDsjM t/WDlnTyY2o9E3mI4RMFR+QgFO7nwErTBrcLVtWe8ivIRscjasS6CynpM0BHVdscMjUL 02k11oc6Ec47J4j1ucth+1H8slbwXkGU/bEAO2yjgrOm5iTyCFO1of/gcpL4zYniegrT ZZ0b9SntSALNhuV1d64ViPbkIjkLWRvMZrpqrgeHWWO2E5uab63YQXkszTnXI5xui60j 8rsNZ2ZkVzWudxwlkoxRId5keYTTGc/chGeVK2KqUCVUwgyBC0N/FGCsMkPKyXWpPfzh dA7Q== X-Gm-Message-State: AD7BkJK/YzoHuxlRnscBYlOp2cmX2R7Gd4fe9zin2y22sKuzi4RYx/S2Yc94k7B2ylFf3Q== X-Received: by 10.194.81.103 with SMTP id z7mr231410wjx.25.1457565387055; Wed, 09 Mar 2016 15:16:27 -0800 (PST) Date: Thu, 10 Mar 2016 00:16:18 +0100 From: Juan Manuel Torres Palma To: libc-alpha@sourceware.org Cc: aoliva@redhat.com Subject: [PATCH v2] Improve debugging for manual safety annotations Message-ID: <20160309231618.GA29413@randy-betty.homestation> MIME-Version: 1.0 Content-Disposition: inline User-Agent: Mutt/1.5.24 (2015-08-30) hello glibc folks, I have submitted and pinged this patch for quite a while already but I get no feedback on it. Seems like I have to elaborate a little bit more on this patch to get some review, so here we go. This patch is quite simple since it barely changes anything critical. It addresses a couple bugs that I spotted while writing documentation for new features in the manual. 1.- Mention the option to build a pdf format of the manual in the documentation. 2.- Fix bug in manual/errno.texi where the function perror(), that was labeled as MT-safe, is actually MT-unsafe, due to race conditions when reading stderr. It seemed to be a typo. 3.- Add awk script manual/chk-typefun.awk that ensures that every function definition in the manual contains information about safety tags. It fixes a FIXME marker set by Alexandre Oliva when creating this script. 4.- Add new debugging information to manual/check-safety.sh, so when building the manual we can get to know which file and line contain the error. In addition, a message with the type of error is displayed too. Fix a small bug in this file that allowed to have MT-safe tags with Mt-Unsafe remarks. As you can see, this patch is *not* critical, but fixes a couple things in the manual that can help to write documentation for new functions in the future. Please if you find any inconvenience, let me know and I will be glad to answer. Cheers, jmtp. ------------------------------------------------------ This patch improves previous safety tags checking script and adds more output in case of errors. Also fixes a couple bugs in the manual building system and adds a new file to check that @deftypefun tags are always follown by @safety. 2016-03-10 Juan Manuel Torres Palma * INSTALL: Regenerated. * manual/check-safety.sh: Fix bugs when finding AS-Unsafe tags and add new debugging layer for this script. * manual/chk-typefun.awk: New file. Searches for @deftypefun that aren't paired with @safety annotations. * manual/errno.texi (perror): Fix wrong tag. * manual/install.texi: Add reference to 'make pdf'. diff --git a/INSTALL b/INSTALL index c70ea9f..ab46add 100644 --- a/INSTALL +++ b/INSTALL @@ -234,7 +234,8 @@ failure occurs. 'make dvi'. You need a working TeX installation to do this. The distribution builds the on-line formatted version of the manual, as Info files, as part of the build process. You can build them manually with -'make info'. +'make info'. Moreover, it's possible to get a copy in PDF format. To +build it, type 'make pdf'. The library has a number of special-purpose configuration parameters which you can find in 'Makeconfig'. These can be overwritten with the diff --git a/manual/check-safety.sh b/manual/check-safety.sh index 2eba000..a3e08fe 100644 --- a/manual/check-safety.sh +++ b/manual/check-safety.sh @@ -24,23 +24,48 @@ # an explicit reason and when there's a reason for unsafety it's not # safe, and that there aren't duplicates remarks. - +# Set to ":" if no error was found, and to "false" if found. success=: +# Gets the name of the file and line where an error was found. +error_ln= + +# Holds the error message for an error. +error_msg= + # If no arguments are given, take all *.texi files in the current directory. test $# != 0 || set *.texi -# FIXME: check that each @deftypefu?n is followed by a @safety note, -# with nothing but @deftypefu?nx and comment lines in between. (There -# might be more stuff too). + +# Function to check errors and set $success. +check_and_set_error () +{ + if [ -n "$error_ln" ] + then + echo "$error_ln:Error $error_msg" + success=false + fi +} + + +# Check that each @deftypefu?n is followed by a @safety note, +# with nothing but @deftypefu?nx and comment lines in between. +# Also indexes are allowed. +error_ln=$(awk -f chk-typefun.awk "$@") +error_msg="unexpected tag between @deftypefun and @safety." +check_and_set_error # Check that all safety remarks have entries for all of MT, AS and AC, # in this order, with an optional prelim note before them. -grep -n '^@safety' "$@" | +error_ln=$(grep -n '^@safety' "$@" | grep -v ':@safety{\(@prelim{}\)\?@mt\(un\)\?safe{.*}'\ -'@as\(un\)\?safe{.*}@ac\(un\)\?safe{.*}}' && -success=false +'@as\(un\)\?safe{.*}@ac\(un\)\?safe{.*}}' | +cut -d':' -f1,2) + +error_msg="safety marks are in incorrect order (MT, AS, AC)." +check_and_set_error + # Check that @mt-started notes appear within @mtsafe or @mtunsafe, # that @as-started notes appear within @assafe or @asunsafe, and that @@ -49,76 +74,108 @@ success=false # unsafe), but let @mt have as, ac or asc before [su], and let @as # have a c (for cancel) before [su]. Also make sure blanks separate # each of the annotations. -grep -n '^@safety' "$@" | +error_ln=$(grep -n '^@safety' "$@" | grep -v ':@safety{\(@prelim{}\)\?'\ '@mt\(un\)\?safe{\(@mt\(asc\?\|ac\)\?[su][^ ]*}\)\?'\ '\( @mt\(asc\?\|ac\)\?[su][^ ]*}\)*}'\ '@as\(un\)\?safe{\(@asc\?[su][^ ]*}\)\?'\ '\( @asc\?[su][^ ]*}\)*}'\ '@ac\(un\)\?safe{\(@ac[su][^ ]*}\)\?'\ -'\( @ac[su][^ ]*}\)*}}' && -success=false +'\( @ac[su][^ ]*}\)*}}' | +cut -d':' -f1,2) + +error_msg="tags are uncorrectly set. Check that every "\ +"remark is placed in the right tag." +check_and_set_error # Make sure safety lines marked as @mtsafe do not contain any # MT-Unsafe remark; that would be @mtu, but there could be as, ac or # asc between mt and u. -grep -n '^@safety.*@mtsafe' "$@" | -grep '@mt\(asc\?\|ac\)?u' "$@" && -success=false +error_ln=$(grep -n '^@safety.*@mtsafe' "$@" | +grep '@mt\(asc\?\|ac\)\?u' | +cut -d':' -f1,2) + +error_msg="@mtsafe tag contains MT-Unsafe remark." +check_and_set_error # Make sure @mtunsafe lines contain at least one @mtu remark (with # optional as, ac or asc between mt and u). -grep -n '^@safety.*@mtunsafe' "$@" | -grep -v '@mtunsafe{.*@mt\(asc\?\|ac\)\?u' && -success=false +error_ln=$(grep -n '^@safety.*@mtunsafe' "$@" | +grep -v '@mtunsafe{.*@mt\(asc\?\|ac\)\?u' | +cut -d':' -f1,2) + +error_msg="@mtunsafe tag empty." +check_and_set_error # Make sure safety lines marked as @assafe do not contain any AS-Unsafe # remark, which could be @asu or @mtasu note (with an optional c # between as and u in both cases). -grep -n '^@safety.*@assafe' "$@" | -grep '@\(mt\)\?asc\?u' && -success=false +error_ln=$(grep -n '^@safety.*@assafe' "$@" | +grep '@\(mt\)\?asc\?u' | +cut -d':' -f1,2) + +error_msg="@assafe tag contains AS-Unsafe remark." +check_and_set_error # Make sure @asunsafe lines contain at least one @asu remark (which # could be @ascu, or @mtasu or even @mtascu). -grep -n '^@safety.*@asunsafe' "$@" | -grep -v '@mtasc\?u.*@asunsafe\|@asunsafe{.*@asc\?u' && -success=false +error_ln=$(grep -n '^@safety.*@asunsafe' "$@" | +grep -v '@mtasc\?u.*@asunsafe\|@asunsafe{.*@asc\?u' | +cut -d':' -f1,2) + +error_msg="@asunsafe tag empty." +check_and_set_error # Make sure safety lines marked as @acsafe do not contain any # AC-Unsafe remark, which could be @acu, @ascu or even @mtacu or # @mtascu. -grep -n '^@safety.*@acsafe' "$@" | -grep '@\(mt\)\?as\?cu' && -success=false +error_ln=$(grep -n '^@safety.*@acsafe' "$@" | +grep '@\(mt\)\?as\?cu' | +cut -d':' -f1,2) + +error_msg="@acsafe tag contains AC-Unsafe remark." +check_and_set_error # Make sure @acunsafe lines contain at least one @acu remark (possibly # implied by @ascu, @mtacu or @mtascu). -grep -n '^@safety.*@acunsafe' "$@" | -grep -v '@\(mtas\?\|as\)cu.*@acunsafe\|@acunsafe{.*@acu' && -success=false +error_ln=$(grep -n '^@safety.*@acunsafe' "$@" | +grep -v '@\(mtas\?\|as\)cu.*@acunsafe\|@acunsafe{.*@acu' | +cut -d':' -f1,2) + +error_msg="@acunsafe tag empty." +check_and_set_error # Make sure there aren't duplicate remarks in the same safety note. -grep -n '^@safety' "$@" | -grep '[^:]\(@\(mt\|a[sc]\)[^ {]*{[^ ]*}\).*[^:]\1' && -success=false +error_ln=$(grep -n '^@safety' "$@" | +grep '[^:]\(@\(mt\|a[sc]\)[^ {]*{[^ ]*}\).*[^:]\1' | +cut -d':' -f1,2) + +error_msg="duplicated remark." +check_and_set_error # Check that comments containing safety remarks do not contain {}s, # that all @mt remarks appear before @as remarks, that in turn appear # before @ac remarks, all properly blank-separated, and that an # optional comment about exclusions is between []s at the end of the # line. -grep -n '^@c \+[^@ ]\+\( dup\)\?'\ +error_ln=$(grep -n '^@c \+[^@ ]\+\( dup\)\?'\ '\( @\(mt\|a[sc]\)[^ ]*\)*\( \[.*\]\)\?$' "$@" | grep -v ':@c *[^@{}]*\( @mt[^ {}]*\)*'\ -'\( @as[^ {}]*\)*\( @ac[^ {}]*\)*\( \[.*\]\)\?$' && -success=false +'\( @as[^ {}]*\)*\( @ac[^ {}]*\)*\( \[.*\]\)\?$' | +cut -d':' -f1,2) + +error_msg="safety remark in wrong order (@mt, @as, @ac), no space "\ +"between remarks or bad format for optional comment." +check_and_set_error # Check that comments containing safety remarks do not contain # duplicate remarks. -grep -n '^@c \+[^@ ]\+\( dup\)\?'\ +error_ln=$(grep -n '^@c \+[^@ ]\+\( dup\)\?'\ '\( @\(mt\|a[sc]\)[^ ]*\)*\( \[.*\]\)\?$' "$@" | -grep '[^:]\(@\(mt\|a[sc]\)[^ ]*\) \(.*[^:]\)\?\1\($\| \)' && -success=false +grep '[^:]\(@\(mt\|a[sc]\)[^ ]*\) \(.*[^:]\)\?\1\($\| \)' | +cut -d':' -f1,2) + +error_msg="duplicated remark in a comment." +check_and_set_error $success diff --git a/manual/chk-typefun.awk b/manual/chk-typefun.awk new file mode 100644 index 0000000..c895a69 --- /dev/null +++ b/manual/chk-typefun.awk @@ -0,0 +1,46 @@ +#! /usr/local/bin/gawk -f + +# Copyright 2016 Free Software Foundation, Inc. +# This file is part of the GNU C Library. + +# The GNU C Library is free software; you can redistribute it and/or +# modify it under the terms of the GNU Lesser General Public +# License as published by the Free Software Foundation; either +# version 2.1 of the License, or (at your option) any later version. + +# The GNU C Library is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +# Lesser General Public License for more details. + +# You should have received a copy of the GNU Lesser General Public +# License along with the GNU C Library; if not, see +# . + + +# Checks that every @deftypefun is follown by a @safety tag. +# Displays an error in case it is not found. + + +/^@deftypefun / { + # Found deftypefun + + # Read next line. If they are comments, keep going. + getline inp + while (match (inp, "^@c(omment)? ") || + match (inp, "^@deftypefunx ") || + match (inp, "^@[cp]index ")) { + + getline inp + } + + # Done reading comments, it's a @safety tag or + # we have to report error. + if (!match (inp, "^@safety{")) { + printf "%s:%d\n", FILENAME, FNR + exit 1 + } + + # If we get here is because tags were correctly + # placed. +} diff --git a/manual/errno.texi b/manual/errno.texi index 1068be3..b14db62 100644 --- a/manual/errno.texi +++ b/manual/errno.texi @@ -1335,7 +1335,7 @@ This function @code{strerror_r} is a GNU extension and it is declared in @comment stdio.h @comment ISO @deftypefun void perror (const char *@var{message}) -@safety{@prelim{}@mtsafe{@mtasurace{:stderr}}@asunsafe{@asucorrupt{} @ascuintl{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{} @acsfd{}}} +@safety{@prelim{}@mtunsafe{@mtasurace{:stderr}}@asunsafe{@asucorrupt{} @ascuintl{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{} @acsfd{}}} @c Besides strerror_r's and some of fprintf's issues, if stderr is not @c oriented yet, create a new stream with a dup of stderr's fd and write @c to that instead of stderr, to avoid orienting it. diff --git a/manual/install.texi b/manual/install.texi index de9d270..1e8d323 100644 --- a/manual/install.texi +++ b/manual/install.texi @@ -266,7 +266,8 @@ To format the @cite{GNU C Library Reference Manual} for printing, type @w{@code{make dvi}}. You need a working @TeX{} installation to do this. The distribution builds the on-line formatted version of the manual, as Info files, as part of the build process. You can build -them manually with @w{@code{make info}}. +them manually with @w{@code{make info}}. Moreover, it's possible +to get a copy in PDF format. To build it, type @w{@code{make pdf}}. The library has a number of special-purpose configuration parameters which you can find in @file{Makeconfig}. These can be overwritten with