From patchwork Thu Feb 11 19:22:19 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: 10831 Received: (qmail 78564 invoked by alias); 11 Feb 2016 19:23:33 -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 78528 invoked by uid 89); 11 Feb 2016 19:23:32 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=-2.6 required=5.0 tests=BAYES_00, FREEMAIL_FROM, RCVD_IN_DNSWL_LOW, SPF_PASS autolearn=ham version=3.3.2 spammy= X-HELO: mail-wm0-f68.google.com X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20130820; h=x-gm-message-state:from:to:cc:subject:date:message-id; bh=biqUETWbyjuUT4oNTa0So5+GHDw7N5232s/azw+/HEc=; b=G9wv/pj6/Y2jes00kabYDZI5eVcGLLktebhwUqKEAnSA66K8wtQDmWBR0kkDt9zACK TWROkDpq10AYG+0cx4CApeFw32jk4++rW7iT3eLgl4OCFtBL2+dCWYnIepkm/IdxwIVE T+BoOfXT7FQlRMnUkb7ykMRIxNioy2W44zYUtnoQLACn0lvFwUFxb9I1ervT6UHW1whn BF9Nt1f8ulnSpduUXfUv09Fq1mgm0MA9cpTGIr/hQktRD+YK3R+Wkryq3xAPXPWdxaV+ NEDhkAv0bmxAxwyPbQ+Y9MzxTCWw/uc0hKzNifDXa9mPEcgzaBzgV/Mn3J6PR/TK7FXV Yv7A== X-Gm-Message-State: AG10YOSv0hhT161E04GGgge7MlFbs/oePspZjIIvnG2WUMRxN9n1Qu3DZQn3DaTMgAMr6w== X-Received: by 10.28.7.72 with SMTP id 69mr187314wmh.50.1455218607304; Thu, 11 Feb 2016 11:23:27 -0800 (PST) From: Juan Manuel Torres Palma To: libc-alpha@sourceware.org Cc: aoliva@redhat.com, joseph@codesourcery.com Subject: [PATCH v2] Improve debugging for manual safety annotations Date: Thu, 11 Feb 2016 20:22:19 +0100 Message-Id: <1455218539-30403-1-git-send-email-j.m.torrespalma@gmail.com> 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-02-11 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..9d17078 --- /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