finish the GNULIB_POSIXCHECK framework

[Bruno Haible]

Currently the framework for using GNULIB_POSIXCHECK is hardly usable:
- It is not documented.
- The user has to remember that they will not be warned about functions
  declared in header files for which they have not requested the Gnulib
  replacement.

This patch fixes both issues.


2018-08-04  Bruno Haible  <address@hidden>

        New module 'posixcheck'.
        * modules/posixcheck: New file.
        * m4/posixcheck.m4: New file.
        * doc/gnulib-tool.texi (Finding POSIX substitutes): New section.
        (Which modules?): Reference it.

diff --git a/doc/gnulib-tool.texi b/doc/gnulib-tool.texi
index 302fe88..e3b8eec 100644
--- a/doc/gnulib-tool.texi
+++ b/doc/gnulib-tool.texi
@@ -44,6 +44,7 @@ a real run without changing anything.
 * Modified imports::            Changing the import specification.
 * Simple update::               Tracking Gnulib development.
 * Source changes::              Impact of Gnulib on your source files.
+* Finding POSIX substitutes::   Determining additional suitable Gnulib modules
 * Modified build rules::        Modifying the build rules of a Gnulib import
 * Multiple instances::          Using Gnulib for both a library and a program
 * gettextize and autopoint::    Caveat: @code{gettextize} and @code{autopoint} 
users!
@@ -58,7 +59,7 @@ a real run without changing anything.
 @section Finding modules
 @cindex Finding modules
 
-There are three ways of finding the names of Gnulib modules that you can use
+There are four ways of finding the names of Gnulib modules that you can use
 in your package:
 
 @itemize
@@ -67,6 +68,10 @@ You have the complete module list, sorted according to 
categories, in
 @url{https://www.gnu.org/software/gnulib/MODULES.html}.
 
 @item
+If you are looking for POSIX function replacements that you don't know about
+yet, follow the procedure described in section @ref{Finding POSIX substitutes}.
+
address@hidden
 If you are looking for a particular POSIX header or function replacement,
 look in the chapters @ref{Header File Substitutes} and
 @ref{Function Substitutes}.  For headers and functions that are provided by
@@ -460,6 +465,48 @@ used to set system dependent flags (such as 
@code{_GNU_SOURCE} on GNU systems),
 and these flags have no effect after any system header file has been included.
 
 
address@hidden Finding POSIX substitutes
address@hidden Finding recommended ISO C and POSIX function substitutes
+
+Gnulib contains a wealth of portability workarounds for ISO C and POSIX
+functions.  They are listed in detail in the chapter @ref{Function 
Substitutes}.
+If you want to know which function substitutes are recommended for your
+package, you can search your source code for ISO C and POSIX functions
+that it uses and read the corresponding sections of said documentation
+chapter.  But this is a tedious task.  Here is an alternative approach
+that makes this task easier.
+
address@hidden
address@hidden
+Add the Gnulib module @samp{posixcheck} to the Gnulib imports of your package,
+as described earlier in this chapter.
+
address@hidden
+Do a @code{make distclean} if you previously built in the top-level directory.
+Then regenerate the Autotools-generated parts of the package.
+
address@hidden
+On a glibc system, build your package.  Pay attention to the compiler warnings.
+Warnings are generated for uses of ISO C and POSIX functions that have
+portability problems or other important pitfalls and for which you have not yet
+imported the corresponding Gnulib module.  If you get, say, a warning
+``warning: call to 'close' declared with attribute warning: close does not
+portably work on sockets - use gnulib module close for portability'',
+put @samp{close} on your list of modules to import.
+
address@hidden
+Add the modules you noted to the Gnulib imports of your package.
+
address@hidden
+Optionally, you can do the same steps again, and make sure that there are no
+warnings left except those that you want to intentionally ignore.
+
address@hidden
+Finally, remove the Gnulib module @samp{posixcheck} from the Gnulib imports,
+and run @code{make distclean}.
address@hidden enumerate
+
+
 @node Modified build rules
 @section Modifying the build rules of a Gnulib import directory
 
diff --git a/m4/posixcheck.m4 b/m4/posixcheck.m4
new file mode 100644
index 0000000..86f906a
--- /dev/null
+++ b/m4/posixcheck.m4
@@ -0,0 +1,12 @@
+# posixcheck.m4 serial 1
+dnl Copyright (C) 2018 Free Software Foundation, Inc.
+dnl This file is free software; the Free Software Foundation
+dnl gives unlimited permission to copy and/or distribute it,
+dnl with or without modifications, as long as this notice is preserved.
+
+AC_DEFUN([gl_POSIXCHECK],
+[
+  AC_DEFINE([GNULIB_POSIXCHECK], [1],
+    [Define to enable warnings for determining which Gnulib modules to use,
+     for portability of POSIX functions.])
+])
diff --git a/modules/posixcheck b/modules/posixcheck
new file mode 100644
index 0000000..85da0a8
--- /dev/null
+++ b/modules/posixcheck
@@ -0,0 +1,58 @@
+Description:
+Enable warnings for determining which Gnulib modules to use,
+for portability of POSIX functions.
+
+Files:
+m4/posixcheck.m4
+
+Depends-on:
+# All modules that depend on 'snippet/warn-on-use'.
+arpa_inet
+ctype
+dirent
+fcntl-h
+iconv-h
+inttypes-incomplete
+langinfo
+locale
+math
+monetary
+netdb
+poll-h
+pty
+search
+signal-h
+spawn
+stdio
+stdlib
+string
+strings
+sys_file
+sys_ioctl
+sys_resource
+sys_select
+sys_socket
+sys_stat
+sys_time
+sys_times
+sys_utsname
+sys_wait
+termios
+time
+unistd
+utime-h
+wchar
+wctype-h
+
+configure.ac:
+gl_POSIXCHECK
+
+Makefile.am:
+
+Include:
+
+License:
+LGPLv2+
+
+Maintainer:
+Bruno Haible