maint: add function attributes to .h files

Add _GL_ATTRIBUTE_NONNULL, _GL_ATTRIBUTE_MALLOC,
_GL_ATTRIBUTE_DEALLOC, _GL_ATTRIBUTE_DALLOC_FREE,
_GL_ATTRIBUTE_RETURNS_NONNULL to .h files when appropriate.
* gl/lib/mbsalign.h, gl/lib/randperm.h, src/chown-core.h:
Include stdlib.h, for the benefit of _GL_ATTRIBUTE_DALLOC_FREE.
* gl/lib/randread.c (randread_free_body): New static function.
(randread_new, randread_free): Use it.
* src/copy.c (valid_options): Remove assert that is no longer
needed because it is now checked statically.

13 files changed, 74 insertions, 36 deletions

diff --git a/gl/lib/cl-strtod.h b/gl/lib/cl-strtod.h
index 51becd3cd..4f1197231 100644
--- a/gl/lib/cl-strtod.h
+++ b/gl/lib/cl-strtod.h
@@ -1,2 +1,4 @@
-double cl_strtod (char const *, char **restrict);
-long double cl_strtold (char const *, char **restrict);
+double cl_strtod (char const *, char **restrict)
+  _GL_ATTRIBUTE_NONNULL ((1));
+long double cl_strtold (char const *, char **restrict)
+  _GL_ATTRIBUTE_NONNULL ((1));
diff --git a/gl/lib/fd-reopen.h b/gl/lib/fd-reopen.h
index 105e36a31..8f4164002 100644
--- a/gl/lib/fd-reopen.h
+++ b/gl/lib/fd-reopen.h
@@ -19,4 +19,4 @@
 
 #include <sys/types.h>
 
-int fd_reopen (int, char const *, int, mode_t);
+int fd_reopen (int, char const *, int, mode_t) _GL_ATTRIBUTE_NONNULL ();
diff --git a/gl/lib/heap.h b/gl/lib/heap.h
index 4dd197133..c3be5f47e 100644
--- a/gl/lib/heap.h
+++ b/gl/lib/heap.h
@@ -20,7 +20,13 @@
 
 #include <stddef.h>
 
-struct heap *heap_alloc (int (*) (void const *, void const *), size_t);
-void heap_free (struct heap *);
-int heap_insert (struct heap *heap, void *item);
-void *heap_remove_top (struct heap *heap);
+struct heap;
+
+void heap_free (struct heap *) _GL_ATTRIBUTE_NONNULL ();
+
+struct heap *heap_alloc (int (*) (void const *, void const *), size_t)
+  _GL_ATTRIBUTE_MALLOC _GL_ATTRIBUTE_DEALLOC (heap_free, 1)
+  _GL_ATTRIBUTE_RETURNS_NONNULL;
+
+int heap_insert (struct heap *heap, void *item) _GL_ATTRIBUTE_NONNULL ();
+void *heap_remove_top (struct heap *heap) _GL_ATTRIBUTE_NONNULL ();
diff --git a/gl/lib/mbsalign.h b/gl/lib/mbsalign.h
index 4fdcac419..ef289da1a 100644
--- a/gl/lib/mbsalign.h
+++ b/gl/lib/mbsalign.h
@@ -15,6 +15,7 @@
    along with this program.  If not, see <https://www.gnu.org/licenses/>.  */
 
 #include <stddef.h>
+#include <stdlib.h>
 
 typedef enum { MBS_ALIGN_LEFT, MBS_ALIGN_RIGHT, MBS_ALIGN_CENTER } mbs_align_t;
 
@@ -53,7 +54,10 @@ enum {
 
 size_t
 mbsalign (char const *src, char *dest, size_t dest_size,
-          size_t *width, mbs_align_t align, int flags);
+          size_t *width, mbs_align_t align, int flags)
+  _GL_ATTRIBUTE_NONNULL ();
 
 char *
-ambsalign (char const *src, size_t *width, mbs_align_t align, int flags);
+ambsalign (char const *src, size_t *width, mbs_align_t align, int flags)
+  _GL_ATTRIBUTE_MALLOC _GL_ATTRIBUTE_DEALLOC_FREE
+  _GL_ATTRIBUTE_NONNULL ();
diff --git a/gl/lib/rand-isaac.h b/gl/lib/rand-isaac.h
index caa38ac3e..9484c0953 100644
--- a/gl/lib/rand-isaac.h
+++ b/gl/lib/rand-isaac.h
@@ -59,7 +59,8 @@ struct isaac_state
     isaac_word a, b, c;		/* Extra variables */
   };
 
-void isaac_seed (struct isaac_state *);
-void isaac_refill (struct isaac_state *, isaac_word[ISAAC_WORDS]);
+void isaac_seed (struct isaac_state *) _GL_ATTRIBUTE_NONNULL ();
+void isaac_refill (struct isaac_state *, isaac_word[ISAAC_WORDS])
+  _GL_ATTRIBUTE_NONNULL ();
 
 #endif
diff --git a/gl/lib/randint.h b/gl/lib/randint.h
index 75a52188d..160152f08 100644
--- a/gl/lib/randint.h
+++ b/gl/lib/randint.h
@@ -32,11 +32,18 @@ typedef uintmax_t randint;
 
 struct randint_source;
 
-struct randint_source *randint_new (struct randread_source *);
-struct randint_source *randint_all_new (char const *, size_t);
+void randint_free (struct randint_source *) _GL_ATTRIBUTE_NONNULL ();
+int randint_all_free (struct randint_source *) _GL_ATTRIBUTE_NONNULL ();
+struct randint_source *randint_new (struct randread_source *)
+  _GL_ATTRIBUTE_MALLOC _GL_ATTRIBUTE_DEALLOC (randint_free, 1)
+  _GL_ATTRIBUTE_NONNULL () _GL_ATTRIBUTE_RETURNS_NONNULL;
+struct randint_source *randint_all_new (char const *, size_t)
+  _GL_ATTRIBUTE_MALLOC _GL_ATTRIBUTE_DEALLOC (randint_all_free, 1)
+  _GL_ATTRIBUTE_NONNULL ();
 struct randread_source *randint_get_source (struct randint_source const *)
-  _GL_ATTRIBUTE_PURE;
-randint randint_genmax (struct randint_source *, randint genmax);
+  _GL_ATTRIBUTE_NONNULL () _GL_ATTRIBUTE_PURE;
+randint randint_genmax (struct randint_source *, randint genmax)
+  _GL_ATTRIBUTE_NONNULL ();
 
 /* Consume random data from *S to generate a random number in the range
    0 .. CHOICES-1.  CHOICES must be nonzero.  */
@@ -46,7 +53,4 @@ randint_choose (struct randint_source *s, randint choices)
   return randint_genmax (s, choices - 1);
 }
 
-void randint_free (struct randint_source *);
-int randint_all_free (struct randint_source *);
-
 #endif
diff --git a/gl/lib/randperm.h b/gl/lib/randperm.h
index 0a0837aa6..b7efbeb11 100644
--- a/gl/lib/randperm.h
+++ b/gl/lib/randperm.h
@@ -1,4 +1,6 @@
 #include "randint.h"
 #include <stddef.h>
+#include <stdlib.h>
 size_t randperm_bound (size_t, size_t) _GL_ATTRIBUTE_CONST;
-size_t *randperm_new (struct randint_source *, size_t, size_t);
+size_t *randperm_new (struct randint_source *, size_t, size_t)
+  _GL_ATTRIBUTE_MALLOC _GL_ATTRIBUTE_DEALLOC_FREE;
diff --git a/gl/lib/randread.c b/gl/lib/randread.c
index 6c29a62e4..d8c5cbaf5 100644
--- a/gl/lib/randread.c
+++ b/gl/lib/randread.c
@@ -146,6 +146,17 @@ get_nonce (void *buffer, size_t bufsize)
   return true;
 }
 
+/* Body of randread_free, broken out to pacify gcc -Wmismatched-dealloc.  */
+
+static int
+randread_free_body (struct randread_source *s)
+{
+  FILE *source = s->source;
+  explicit_bzero (s, sizeof *s);
+  free (s);
+  return source ? fclose (source) : 0;
+}
+
 /* Create and initialize a random data source from NAME, or use a
    reasonable default source if NAME is null.  BYTES_BOUND is an upper
    bound on the number of bytes that will be needed.  If zero, it is a
@@ -182,7 +193,7 @@ randread_new (char const *name, size_t bytes_bound)
                            MIN (sizeof s->buf.isaac.state.m, bytes_bound)))
             {
               int e = errno;
-              randread_free (s);
+              randread_free_body (s);
               errno = e;
               return NULL;
             }
@@ -303,8 +314,5 @@ randread (struct randread_source *s, void *buf, size_t size)
 int
 randread_free (struct randread_source *s)
 {
-  FILE *source = s->source;
-  explicit_bzero (s, sizeof *s);
-  free (s);
-  return (source ? fclose (source) : 0);
+  return randread_free_body (s);
 }
diff --git a/gl/lib/randread.h b/gl/lib/randread.h
index b5534f301..d4151860b 100644
--- a/gl/lib/randread.h
+++ b/gl/lib/randread.h
@@ -24,10 +24,15 @@
 
 struct randread_source;
 
-struct randread_source *randread_new (char const *, size_t);
-void randread (struct randread_source *, void *, size_t);
-void randread_set_handler (struct randread_source *, void (*) (void const *));
-void randread_set_handler_arg (struct randread_source *, void const *);
-int randread_free (struct randread_source *);
+int randread_free (struct randread_source *) _GL_ATTRIBUTE_NONNULL ();
+struct randread_source *randread_new (char const *, size_t)
+  _GL_ATTRIBUTE_MALLOC _GL_ATTRIBUTE_DEALLOC (randread_free, 1)
+  _GL_ATTRIBUTE_RETURNS_NONNULL;
+void randread (struct randread_source *, void *, size_t)
+  _GL_ATTRIBUTE_NONNULL ();
+void randread_set_handler (struct randread_source *, void (*) (void const *))
+  _GL_ATTRIBUTE_NONNULL ();
+void randread_set_handler_arg (struct randread_source *, void const *)
+  _GL_ATTRIBUTE_NONNULL ((1));
 
 #endif
diff --git a/gl/lib/root-dev-ino.h b/gl/lib/root-dev-ino.h
index 9cc9dad7e..3f73c0ab7 100644
--- a/gl/lib/root-dev-ino.h
+++ b/gl/lib/root-dev-ino.h
@@ -22,7 +22,7 @@
 # include "same-inode.h"
 
 struct dev_ino *
-get_root_dev_ino (struct dev_ino *root_d_i);
+get_root_dev_ino (struct dev_ino *root_d_i) _GL_ATTRIBUTE_NONNULL ();
 
 /* These macros are common to the programs that support the
    --preserve-root and --no-preserve-root options.  */
diff --git a/gl/lib/strnumcmp.h b/gl/lib/strnumcmp.h
index d7f273326..f6a02b21c 100644
--- a/gl/lib/strnumcmp.h
+++ b/gl/lib/strnumcmp.h
@@ -1,2 +1,4 @@
-int strintcmp (char const *, char const *) _GL_ATTRIBUTE_PURE;
-int strnumcmp (char const *, char const *, int, int) _GL_ATTRIBUTE_PURE;
+int strintcmp (char const *, char const *)
+  _GL_ATTRIBUTE_NONNULL () _GL_ATTRIBUTE_PURE;
+int strnumcmp (char const *, char const *, int, int)
+  _GL_ATTRIBUTE_NONNULL () _GL_ATTRIBUTE_PURE;
diff --git a/gl/lib/xdectoint.h b/gl/lib/xdectoint.h
index a1a381240..e977206ce 100644
--- a/gl/lib/xdectoint.h
+++ b/gl/lib/xdectoint.h
@@ -22,10 +22,12 @@
 
 # define _DECLARE_XDECTOINT(name, type) \
   type name (char const *n_str, type min, type max, \
-             char const *suffixes, char const *err, int err_exit);
+             char const *suffixes, char const *err, int err_exit) \
+    _GL_ATTRIBUTE_NONNULL ((1, 5));
 # define _DECLARE_XNUMTOINT(name, type) \
   type name (char const *n_str, int base, type min, type max, \
-             char const *suffixes, char const *err, int err_exit);
+             char const *suffixes, char const *err, int err_exit) \
+    _GL_ATTRIBUTE_NONNULL ((1, 6));
 
 _DECLARE_XDECTOINT (xdectoimax, intmax_t)
 _DECLARE_XDECTOINT (xdectoumax, uintmax_t)
diff --git a/gl/lib/xfts.h b/gl/lib/xfts.h
index f903f4804..0b129aaa4 100644
--- a/gl/lib/xfts.h
+++ b/gl/lib/xfts.h
@@ -3,8 +3,10 @@
 
 FTS *
 xfts_open (char * const *, int options,
-           int (*) (const FTSENT **, const FTSENT **));
+           int (*) (const FTSENT **, const FTSENT **))
+  _GL_ATTRIBUTE_MALLOC _GL_ATTRIBUTE_DEALLOC (fts_close, 1)
+  _GL_ATTRIBUTE_NONNULL ((1)) _GL_ATTRIBUTE_RETURNS_NONNULL;
 
 bool
 cycle_warning_required (FTS const *fts, FTSENT const *ent)
-  _GL_ATTRIBUTE_PURE;
+  _GL_ATTRIBUTE_NONNULL () _GL_ATTRIBUTE_PURE;