--- a/ChangeLog	Fri Aug 03 10:36:24 2018 -0700
+++ b/ChangeLog	Sat Aug 04 17:25:57 2018 +0200
@@ -1,3 +1,11 @@
+2018-08-04  Bruno Haible  <bruno@clisp.org>
+
+	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.
+
 2018-08-01  Assaf Gordon <assafgordon@gmail.com>
 
 	dfa: fix memory leak

--- a/doc/gnulib-tool.texi	Fri Aug 03 10:36:24 2018 -0700
+++ b/doc/gnulib-tool.texi	Sat Aug 04 17:25:57 2018 +0200
@@ -44,6 +44,7 @@
 * 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 @@
 @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 @@
 @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}.
+
+@item
 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 @@
 and these flags have no effect after any system header file has been included.
 
 
+@node Finding POSIX substitutes
+@section 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.
+
+@enumerate
+@item
+Add the Gnulib module @samp{posixcheck} to the Gnulib imports of your package,
+as described earlier in this chapter.
+
+@item
+Do a @code{make distclean} if you previously built in the top-level directory.
+Then regenerate the Autotools-generated parts of the package.
+
+@item
+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.
+
+@item
+Add the modules you noted to the Gnulib imports of your package.
+
+@item
+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.
+
+@item
+Finally, remove the Gnulib module @samp{posixcheck} from the Gnulib imports,
+and run @code{make distclean}.
+@end enumerate
+
+
 @node Modified build rules
 @section Modifying the build rules of a Gnulib import directory
 

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/m4/posixcheck.m4	Sat Aug 04 17:25:57 2018 +0200
@@ -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.])
+])

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/modules/posixcheck	Sat Aug 04 17:25:57 2018 +0200
@@ -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