diff options
Diffstat (limited to 'manual')
| -rw-r--r-- | manual/Makefile | 5 | ||||
| -rw-r--r-- | manual/conf.texi | 12 | ||||
| -rw-r--r-- | manual/errno.texi | 30 | ||||
| -rw-r--r-- | manual/signal.texi | 10 | ||||
| -rw-r--r-- | manual/stdio.texi | 8 | ||||
| -rw-r--r-- | manual/summary-check.awk | 139 | ||||
| -rw-r--r-- | manual/summary.awk | 17 | ||||
| -rw-r--r-- | manual/terminal.texi | 14 | ||||
| -rw-r--r-- | manual/time.texi | 2 |
9 files changed, 196 insertions, 41 deletions
diff --git a/manual/Makefile b/manual/Makefile index 44c0fd4f68..9945a4ff17 100644 --- a/manual/Makefile +++ b/manual/Makefile @@ -47,6 +47,7 @@ add-chapters = $(wildcard $(foreach d, $(add-ons), ../$d/$d.texi)) appendices = lang.texi header.texi install.texi maint.texi platform.texi \ contrib.texi licenses = freemanuals.texi lgpl-2.1.texi fdl-1.3.texi +tests = summary-check -include $(objpfx)texis $(objpfx)texis: texis.awk $(chapters) $(add-chapters) $(appendices) $(licenses) @@ -93,6 +94,10 @@ $(objpfx)stamp-summary: summary.awk $(filter-out $(objpfx)summary.texi, \ $(move-if-change) $(objpfx)summary-tmp $(objpfx)summary.texi touch $@ +$(objpfx)summary-check.c: summary-check.awk $(objpfx)summary.texi + $(AWK) -f $^ > $@.new + mv -f $@.new $@ + # Generate a file which can be added to the `dir' content to provide direct # access to the documentation of the function, variables, and other # definitions. diff --git a/manual/conf.texi b/manual/conf.texi index 7eb8b3625a..722b9bbd35 100644 --- a/manual/conf.texi +++ b/manual/conf.texi @@ -56,7 +56,7 @@ with @samp{_POSIX}, which gives the lowest value that the limit is allowed to have on @emph{any} POSIX system. @xref{Minimums}. @cindex limits, program argument size -@comment limits.h +@comment limits.h (optional) @comment POSIX.1 @deftypevr Macro int ARG_MAX If defined, the unvarying maximum combined length of the @var{argv} and @@ -64,7 +64,7 @@ If defined, the unvarying maximum combined length of the @var{argv} and @end deftypevr @cindex limits, number of processes -@comment limits.h +@comment limits.h (optional) @comment POSIX.1 @deftypevr Macro int CHILD_MAX If defined, the unvarying maximum number of processes that can exist @@ -74,7 +74,7 @@ Resources}. @end deftypevr @cindex limits, number of open files -@comment limits.h +@comment limits.h (optional) @comment POSIX.1 @deftypevr Macro int OPEN_MAX If defined, the unvarying maximum number of files that a single process @@ -82,7 +82,7 @@ can have open simultaneously. In BSD and GNU, this is controlled by the @code{RLIMIT_NOFILE} resource limit; @pxref{Limits on Resources}. @end deftypevr -@comment limits.h +@comment limits.h (optional) @comment POSIX.1 @deftypevr Macro int STREAM_MAX If defined, the unvarying maximum number of streams that a single @@ -90,7 +90,7 @@ process can have open simultaneously. @xref{Opening Streams}. @end deftypevr @cindex limits, time zone name length -@comment limits.h +@comment limits.h (optional) @comment POSIX.1 @deftypevr Macro int TZNAME_MAX If defined, the unvarying maximum length of a time zone name. @@ -1539,7 +1539,7 @@ there is no actual limit except that imposed by the available virtual memory, but there is no way that the library can tell you this.) @end deftypevr -@comment limits.h +@comment limits.h (optional) @comment POSIX.2 @deftypevr Macro int EQUIV_CLASS_MAX The maximum number of weights that can be assigned to an entry of the diff --git a/manual/errno.texi b/manual/errno.texi index 2a3c004b2a..f6277cf75f 100644 --- a/manual/errno.texi +++ b/manual/errno.texi @@ -714,7 +714,7 @@ Directory not empty, where an empty directory was expected. Typically, this error occurs when you are trying to delete a directory. @end deftypevr -@comment errno.h +@comment errno.h (optional) @comment BSD: Too many processes @deftypevr Macro int EPROCLIM @comment errno 67 @c DO NOT REMOVE @@ -758,35 +758,35 @@ already specifies an NFS-mounted file. properly on @gnuhurdsystems{}, making this error code impossible.) @end deftypevr -@comment errno.h +@comment errno.h (optional) @comment BSD: RPC struct is bad @deftypevr Macro int EBADRPC @comment errno 72 @c DO NOT REMOVE ??? @end deftypevr -@comment errno.h +@comment errno.h (optional) @comment BSD: RPC version wrong @deftypevr Macro int ERPCMISMATCH @comment errno 73 @c DO NOT REMOVE ??? @end deftypevr -@comment errno.h +@comment errno.h (optional) @comment BSD: RPC program not available @deftypevr Macro int EPROGUNAVAIL @comment errno 74 @c DO NOT REMOVE ??? @end deftypevr -@comment errno.h +@comment errno.h (optional) @comment BSD: RPC program version wrong @deftypevr Macro int EPROGMISMATCH @comment errno 75 @c DO NOT REMOVE ??? @end deftypevr -@comment errno.h +@comment errno.h (optional) @comment BSD: RPC bad procedure for program @deftypevr Macro int EPROCUNAVAIL @comment errno 76 @c DO NOT REMOVE @@ -803,7 +803,7 @@ it can result from an operation to an NFS server running another operating system. @end deftypevr -@comment errno.h +@comment errno.h (optional) @comment BSD: Inappropriate file type or format @deftypevr Macro int EFTYPE @comment errno 79 @c DO NOT REMOVE @@ -814,14 +814,14 @@ On some systems @code{chmod} returns this error if you try to set the sticky bit on a non-directory file; @pxref{Setting Permissions}. @end deftypevr -@comment errno.h +@comment errno.h (optional) @comment BSD: Authentication error @deftypevr Macro int EAUTH @comment errno 80 @c DO NOT REMOVE ??? @end deftypevr -@comment errno.h +@comment errno.h (optional) @comment BSD: Need authenticator @deftypevr Macro int ENEEDAUTH @comment errno 81 @c DO NOT REMOVE @@ -865,7 +865,7 @@ While decoding a multibyte character the function came along an invalid or an incomplete sequence of bytes or the given wide character is invalid. @end deftypevr -@comment errno.h +@comment errno.h (optional) @comment GNU: Inappropriate operation for background process @deftypevr Macro int EBACKGROUND @comment errno 100 @c DO NOT REMOVE @@ -877,7 +877,7 @@ it into a @code{SIGTTIN} or @code{SIGTTOU} signal. @xref{Job Control}, for information on process groups and these signals. @end deftypevr -@comment errno.h +@comment errno.h (optional) @comment GNU: Translator died @deftypevr Macro int EDIED @comment errno 101 @c DO NOT REMOVE @@ -886,7 +886,7 @@ translated by a program and the translator program dies while starting up, before it has connected to the file. @end deftypevr -@comment errno.h +@comment errno.h (optional) @comment GNU: ? @deftypevr Macro int ED @comment errno 102 @c DO NOT REMOVE @@ -895,21 +895,21 @@ The experienced user will know what is wrong. @c Don't change it. @end deftypevr -@comment errno.h +@comment errno.h (optional) @comment GNU: You really blew it this time @deftypevr Macro int EGREGIOUS @comment errno 103 @c DO NOT REMOVE You did @strong{what}? @end deftypevr -@comment errno.h +@comment errno.h (optional) @comment GNU: Computer bought the farm @deftypevr Macro int EIEIO @comment errno 104 @c DO NOT REMOVE Go home and have a glass of warm, dairy-fresh milk. @end deftypevr -@comment errno.h +@comment errno.h (optional) @comment GNU: Gratuitous error @deftypevr Macro int EGRATUITOUS @comment errno 105 @c DO NOT REMOVE diff --git a/manual/signal.texi b/manual/signal.texi index adcda37520..1b0540258d 100644 --- a/manual/signal.texi +++ b/manual/signal.texi @@ -446,9 +446,9 @@ probably only see @code{SIGTRAP} if it is somehow executing bad instructions. @end deftypevr -@comment signal.h +@comment signal.h (optional) @comment BSD -@deftypevr Macro int SIGEMT +@deftypevr Macro int SIGEMT Emulator trap; this results from certain unimplemented instructions which might be emulated in software, or the operating system's failure to properly emulate them. @@ -456,7 +456,7 @@ failure to properly emulate them. @comment signal.h @comment Unix -@deftypevr Macro int SIGSYS +@deftypevr Macro int SIGSYS Bad system call; that is to say, the instruction to trap to the operating system was executed, but the code number for the system call to perform was invalid. @@ -798,7 +798,7 @@ Another cause of @code{SIGPIPE} is when you try to output to a socket that isn't connected. @xref{Sending Data}. @end deftypevr -@comment signal.h +@comment signal.h (optional) @comment GNU @deftypevr Macro int SIGLOST @cindex lost resource signal @@ -861,7 +861,7 @@ When the signal arrives, it should fetch the new screen size and reformat its display accordingly. @end deftypevr -@comment signal.h +@comment signal.h (optional) @comment BSD @deftypevr Macro int SIGINFO Information request. On 4.4 BSD and @gnuhurdsystems{}, this signal is sent diff --git a/manual/stdio.texi b/manual/stdio.texi index 3f9be9bc58..e659c52e10 100644 --- a/manual/stdio.texi +++ b/manual/stdio.texi @@ -5053,26 +5053,26 @@ otherwise. @comment stdio.h @comment GNU -@deftp {Data Type} cookie_read_function +@deftp {Data Type} cookie_read_function_t This is the data type that the read function for a custom stream should have. If you declare the function as shown above, this is the type it will have. @end deftp @comment stdio.h @comment GNU -@deftp {Data Type} cookie_write_function +@deftp {Data Type} cookie_write_function_t The data type of the write function for a custom stream. @end deftp @comment stdio.h @comment GNU -@deftp {Data Type} cookie_seek_function +@deftp {Data Type} cookie_seek_function_t The data type of the seek function for a custom stream. @end deftp @comment stdio.h @comment GNU -@deftp {Data Type} cookie_close_function +@deftp {Data Type} cookie_close_function_t The data type of the close function for a custom stream. @end deftp diff --git a/manual/summary-check.awk b/manual/summary-check.awk new file mode 100644 index 0000000000..b3e447fa1d --- /dev/null +++ b/manual/summary-check.awk @@ -0,0 +1,139 @@ +# awk script to create a C file from summary.texinfo +# Copyright (C) 2013 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/>. + +# This script groks the summary.texi (summary.awk output) format. +# It produces a compilable C file attempts to refer to each declaration +# in summary.texi so as to verify that the types in the manual match the +# types in the code. + +BEGIN { + wraps["@w{"] = 1; + wraps["@t{"] = 1; + wraps["@emph{"] = 1; + + print "/* This file is generated by summary-check.awk; DO NOT EDIT! */"; + print ""; +} + +NF == 2 && $1 == "@comment" { + ident = $2; + optional = 0; + next +} +NF == 3 && $1 == "@comment" && $3 = "(optional)" { + ident = $2; + optional = 1; + next +} +NF >= 4 && $1 == "@c" { + source = $2; + lineno = $3; + flavor = $4; + for (i = 5; i <= NF; ++i) + flavor = flavor " " $i; + next +} +$1 == "@item" { + $1 = ""; + gsub(/@var{[^}]+}/, ""); + gsub(/@dots{}/, "..."); + gsub(/@\*/, " "); + decl = $0 ";"; + for (wrap in wraps) { + len = length(wrap); + while ((first = match(decl, wrap)) > 0) { + depth = 1; + for (i = first + len; i < length(decl); ++i) { + c = substr(decl, i, 1); + if (c == "{") ++depth; + else if (c == "}" && --depth == 0) { + left = substr(decl, 1, first - 1); + middle = substr(decl, first + len, i - (first + len)); + right = substr(decl, i + 1); + decl = left middle right; + break; + } + } + } + } + sub(/\.\.\.,.+);/, "...);", decl); # execle + sub(/\[,[^],]+\]/, ", ...", decl); # open + next +} + +/^@file{/ { + gsub(/[^a-zA-Z0-9_]/, "", ident); + undef = 1; + if (flavor ~ /@defvrx?/) { + # These are used for feature-test macros. There is nothing we can test. + next; + } + if (flavor ~ /@itemx?/ || flavor == "@vindex") { + # These are used for macros, but we have no type information. + next; + } + if (flavor == "@defvar") { + # These are used for variables, but we have no type information. + next; + } + if (flavor == "@defmac") { + # These are used for function-like macros, but we have no type information. + next; + } + if (flavor ~ /^@deftypevrx? {Data type}$/ || flavor == "@deftp") { + # This is a type. We can just test that it's usable. + decl = "extern " ident " test_" ident ";"; + } + else if (flavor ~ /^@deftypevrx?/) { + # These are used for macros. + sub(ident, "test_" ident " (void) { return " ident "; }", decl); + undef = 0 + } + + if (decl ~ /float-type/ || decl ~ /real-floating/) { + # Special case: these are function-like macros that + # cannot be redeclared. There isn't a simple way to test. + next + } + + if (ident in seen) + next; + seen[ident] = 1 + + gsub(/,/, ""); + for (i = 1; i <= NF && $i ~ /@file{[^}]+}/; ++i) { + header = gensub(/@file{([^}]+)}/, "\\1", 1, $i); + print "#include", "<" header ">"; + } + if (optional) + print "#ifdef", ident; + else if (undef) + print "#undef", ident; + print "#", lineno, "\"" source "\""; + print decl; + if (optional) + print "#endif", "/*", ident, "*/"; +} + +END { + print ""; + print "int main (void)"; + print "{"; + print " return 0;"; + print "}"; +} diff --git a/manual/summary.awk b/manual/summary.awk index 5ebced62a7..cd68ae6085 100644 --- a/manual/summary.awk +++ b/manual/summary.awk @@ -88,17 +88,22 @@ $1 == "@node" { node=$2; } $1 == "@comment" && $2 ~ /\.h$/ { header="@file{" $2 "}"; + optional = 0; + if ($NF == "(optional)") { + optional = 1; + --NF; + } for (i = 3; i <= NF; ++i) header=header ", @file{" $i "}" } -$1 == "@comment" && $2 == "(none)" { header = -1; } +$1 == "@comment" && $2 == "(none)" { header = -1; optional = 0; } $1 == "@comment" && header != 0 { std=$2; for (i=3;i<=NF;++i) std=std " " $i } header != 0 && $1 ~ /@def|@item|@vindex/ \ - { defn=""; name=""; curly=0; n=1; + { defn=""; name=""; curly=0; n=1; flavor=""; for (i = 2; i <= NF; ++i) { if ($i ~ /^{/ && $i !~ /}/) { curly=1 @@ -124,9 +129,15 @@ header != 0 && $1 ~ /@def|@item|@vindex/ \ name=word ++n } + if (flavor == "") { + flavor = $1; + if (flavor ~ /^@deftypevrx?/) + flavor = flavor " {" word "}"; + } } } - printf "@comment %s%c", name, 12 # FF + printf "@comment %s%s%c", name, optional ? " (optional)" : "", 12 # FF + printf "@c %s %d %s%c", FILENAME, FNR, flavor, 12 printf "@item%s%c%c", defn, 12, 12 if (header != -1) printf "%s ", header; printf "(%s): @ref{%s}.%c\n", std, node, 12; diff --git a/manual/terminal.texi b/manual/terminal.texi index 9e9c057095..3bd4d029d6 100644 --- a/manual/terminal.texi +++ b/manual/terminal.texi @@ -752,27 +752,27 @@ This specifies eight bits per byte. The following four bits are BSD extensions; these exist only on BSD systems and @gnuhurdsystems{}. -@comment termios.h +@comment termios.h (optional) @comment BSD @deftypevr Macro tcflag_t CCTS_OFLOW If this bit is set, enable flow control of output based on the CTS wire (RS232 protocol). @end deftypevr -@comment termios.h +@comment termios.h (optional) @comment BSD @deftypevr Macro tcflag_t CRTS_IFLOW If this bit is set, enable flow control of input based on the RTS wire (RS232 protocol). @end deftypevr -@comment termios.h +@comment termios.h (optional) @comment BSD @deftypevr Macro tcflag_t MDMBUF If this bit is set, enable carrier-based flow control of output. @end deftypevr -@comment termios.h +@comment termios.h (optional) @comment BSD @deftypevr Macro tcflag_t CIGNORE If this bit is set, it says to ignore the control modes and line speed @@ -940,7 +940,7 @@ attempt to write to the terminal. @xref{Access to the Terminal}. The following bits are BSD extensions; they exist only on BSD systems and @gnuhurdsystems{}. -@comment termios.h +@comment termios.h (optional) @comment BSD @deftypevr Macro tcflag_t ALTWERASE This bit determines how far the WERASE character should erase. The @@ -1394,7 +1394,7 @@ mechanism, the program should send a @code{SIGTSTP} signal to the process group of the process, not just to the process itself. @xref{Signaling Another Process}. -@comment termios.h +@comment termios.h (optional) @comment BSD @deftypevr Macro int VDSUSP @cindex DSUSP character @@ -1501,7 +1501,7 @@ output buffer. Typing any other character resets the flag. This character is available on BSD systems and @gnulinuxhurdsystems{}. @end deftypevr -@comment termios.h +@comment termios.h (optional) @comment BSD @deftypevr Macro int VSTATUS @cindex STATUS character diff --git a/manual/time.texi b/manual/time.texi index ff31e284fd..31755df2f6 100644 --- a/manual/time.texi +++ b/manual/time.texi @@ -300,7 +300,7 @@ these are the actual amounts of time; not relative to any event. @xref{Creating a Process}. @end deftp -@comment time.h +@comment time.h (optional) @comment POSIX.1 @deftypevr Macro int CLK_TCK This is an obsolete name for the number of clock ticks per second. Use |