[v2] Improve debugging for manual safety annotations
Commit Message
From: Juan Manuel Torres Palma <jmtorrespalma@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.
2015-08-31 Juan Manuel Torres Palma <j.m.torrespalma@gmail.com>
* 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'.
Comments
Ping.
2015-08-31 20:56 GMT+09:00 Juan Manuel Torres Palma <j.m.torrespalma@gmail.com>:
> From: Juan Manuel Torres Palma <jmtorrespalma@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.
>
> 2015-08-31 Juan Manuel Torres Palma <j.m.torrespalma@gmail.com>
>
> * 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 d55de5d..a35c297 100644
> --- a/INSTALL
> +++ b/INSTALL
> @@ -223,7 +223,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 d7c2ca5..9ca50cc 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..10a0ca4
> --- /dev/null
> +++ b/manual/chk-typefun.awk
> @@ -0,0 +1,46 @@
> +#! /usr/local/bin/gawk -f
> +
> +# Copyright 2015 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
> +# <http://www.gnu.org/licenses/>.
> +
> +
> +# 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 63c41b0..1ebcca5 100644
> --- a/manual/install.texi
> +++ b/manual/install.texi
> @@ -256,7 +256,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
> --
> 2.1.0
>
Ping^2
2015-09-04 0:28 GMT+02:00 Juan Manuel Torres Palma <j.m.torrespalma@gmail.com>:
> Ping.
>
> 2015-08-31 20:56 GMT+09:00 Juan Manuel Torres Palma <j.m.torrespalma@gmail.com>:
>> From: Juan Manuel Torres Palma <jmtorrespalma@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.
>>
>> 2015-08-31 Juan Manuel Torres Palma <j.m.torrespalma@gmail.com>
>>
>> * 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 d55de5d..a35c297 100644
>> --- a/INSTALL
>> +++ b/INSTALL
>> @@ -223,7 +223,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 d7c2ca5..9ca50cc 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..10a0ca4
>> --- /dev/null
>> +++ b/manual/chk-typefun.awk
>> @@ -0,0 +1,46 @@
>> +#! /usr/local/bin/gawk -f
>> +
>> +# Copyright 2015 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
>> +# <http://www.gnu.org/licenses/>.
>> +
>> +
>> +# 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 63c41b0..1ebcca5 100644
>> --- a/manual/install.texi
>> +++ b/manual/install.texi
>> @@ -256,7 +256,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
>> --
>> 2.1.0
>>
>
>
>
> --
> Juan Manuel Torres Palma.
> Computer Science Student at Universidad de Granada.
I'd suggest that when pinging you might want to CC experts on the relevant
code (Alexandre Oliva in the case of anything related to safety
annotations).
@@ -223,7 +223,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
@@ -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
new file mode 100644
@@ -0,0 +1,46 @@
+#! /usr/local/bin/gawk -f
+
+# Copyright 2015 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
+# <http://www.gnu.org/licenses/>.
+
+
+# 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.
+}
@@ -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.
@@ -256,7 +256,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