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.

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));

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 ();

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 ();

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 ();

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

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

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;

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);
 }

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

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.  */

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;

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)

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;

src/blake2/b2sum.h

@@ -13,7 +13,8 @@
    https://blake2.net.
 */
 
-int blake2b_stream( FILE *stream, void *resstream, size_t outbytes );
+int blake2b_stream (FILE *stream, void *resstream, size_t outbytes)
+  _GL_ATTRIBUTE_NONNULL ((1));
 typedef int ( *blake2fn )( FILE *, void *, size_t );
 #define BLAKE2S_OUTBYTES 32
 #define BLAKE2B_OUTBYTES 64

src/blake2/blake2.h

@@ -152,7 +152,8 @@ extern "C" {
 
   int blake2b_init( blake2b_state *S, size_t outlen );
   int blake2b_init_key( blake2b_state *S, size_t outlen, const void *key, size_t keylen );
-  int blake2b_init_param( blake2b_state *S, const blake2b_param *P );
+  int blake2b_init_param (blake2b_state *S, const blake2b_param *P)
+    _GL_ATTRIBUTE_NONNULL ();
   int blake2b_update( blake2b_state *S, const void *in, size_t inlen );
   int blake2b_final( blake2b_state *S, void *out, size_t outlen );
 

src/chown-core.h

@@ -19,6 +19,7 @@
 # define CHOWN_CORE_H
 
 # include "dev-ino.h"
+# include <stdlib.h>
 
 enum Change_status
 {
@@ -72,15 +73,20 @@ void
 chopt_free (struct Chown_option *);
 
 char *
-gid_to_name (gid_t) _GL_ATTRIBUTE_MALLOC;
+gid_to_name (gid_t)
+  _GL_ATTRIBUTE_MALLOC _GL_ATTRIBUTE_DEALLOC_FREE
+  _GL_ATTRIBUTE_RETURNS_NONNULL;
 
 char *
-uid_to_name (uid_t) _GL_ATTRIBUTE_MALLOC;
+uid_to_name (uid_t)
+  _GL_ATTRIBUTE_MALLOC _GL_ATTRIBUTE_DEALLOC_FREE
+  _GL_ATTRIBUTE_RETURNS_NONNULL;
 
 bool
 chown_files (char **files, int bit_flags,
              uid_t uid, gid_t gid,
              uid_t required_uid, gid_t required_gid,
-             struct Chown_option const *chopt);
+             struct Chown_option const *chopt)
+  _GL_ATTRIBUTE_NONNULL ();
 
 #endif /* CHOWN_CORE_H */

src/cksum.h

@@ -9,7 +9,8 @@ crc_sum_stream (FILE *stream, void *resstream, uintmax_t *length);
 extern void
 output_crc (char const *file, int binary_file, void const *digest,
             bool tagged, unsigned char delim, bool args _GL_UNUSED,
-            uintmax_t length _GL_UNUSED);
+            uintmax_t length _GL_UNUSED)
+  _GL_ATTRIBUTE_NONNULL ((3));
 
 extern bool
 cksum_pclmul (FILE *fp, uint_fast32_t *crc_out, uintmax_t *length_out);

src/copy.c

@@ -3071,7 +3071,6 @@ ATTRIBUTE_PURE
 static bool
 valid_options (const struct cp_options *co)
 {
-  assert (co != NULL);
   assert (VALID_BACKUP_TYPE (co->backup_type));
   assert (VALID_SPARSE_MODE (co->sparse_mode));
   assert (VALID_REFLINK_MODE (co->reflink_mode));

src/copy.h

@@ -289,23 +289,27 @@ int rpl_rename (char const *, char const *);
 
 bool copy (char const *src_name, char const *dst_name,
            bool nonexistent_dst, const struct cp_options *options,
-           bool *copy_into_self, bool *rename_succeeded);
+           bool *copy_into_self, bool *rename_succeeded)
+  _GL_ATTRIBUTE_NONNULL ((1, 2, 4, 5));
 
 extern bool set_process_security_ctx (char const *src_name,
                                       char const *dst_name,
                                       mode_t mode, bool new_dst,
-                                      const struct cp_options *x);
+                                      const struct cp_options *x)
+  _GL_ATTRIBUTE_NONNULL ();
 
 extern bool set_file_security_ctx (char const *dst_name,
-                                   bool recurse, const struct cp_options *x);
+                                   bool recurse, const struct cp_options *x)
+  _GL_ATTRIBUTE_NONNULL ();
 
-void dest_info_init (struct cp_options *);
-void dest_info_free (struct cp_options *);
-void src_info_init (struct cp_options *);
-void src_info_free (struct cp_options *);
+void dest_info_init (struct cp_options *) _GL_ATTRIBUTE_NONNULL ();
+void dest_info_free (struct cp_options *) _GL_ATTRIBUTE_NONNULL ();
+void src_info_init (struct cp_options *) _GL_ATTRIBUTE_NONNULL ();
+void src_info_free (struct cp_options *) _GL_ATTRIBUTE_NONNULL ();
 
-void cp_options_default (struct cp_options *);
-bool chown_failure_ok (struct cp_options const *) _GL_ATTRIBUTE_PURE;
+void cp_options_default (struct cp_options *) _GL_ATTRIBUTE_NONNULL ();
+bool chown_failure_ok (struct cp_options const *)
+  _GL_ATTRIBUTE_NONNULL () _GL_ATTRIBUTE_PURE;
 mode_t cached_umask (void);
 
 #endif

src/cp-hash.h

@@ -1,5 +1,6 @@
 void hash_init (void);
 void forget_all (void);
 void forget_created (ino_t ino, dev_t dev);
-char *remember_copied (char const *node, ino_t ino, dev_t dev);
+char *remember_copied (char const *node, ino_t ino, dev_t dev)
+  _GL_ATTRIBUTE_NONNULL ();
 char *src_to_dest_lookup (ino_t ino, dev_t dev);

src/expand-common.h

@@ -32,12 +32,13 @@ add_tab_stop (uintmax_t tabval);
 /* Add the comma or blank separated list of tab stops STOPS
    to the list of tab stops.  */
 extern void
-parse_tab_stops (char const *stops);
+parse_tab_stops (char const *stops) _GL_ATTRIBUTE_NONNULL ();
 
 /* TODO: Document */
 extern uintmax_t
-get_next_tab_column (const uintmax_t column, size_t* tab_index,
-                     bool* last_tab);
+get_next_tab_column (const uintmax_t column, size_t *tab_index,
+                     bool *last_tab)
+  _GL_ATTRIBUTE_NONNULL ((3));
 
 /* Called after all command-line options have been parsed,
    sets the final tab-stops values */

src/find-mount-point.h

@@ -17,4 +17,4 @@
 #include <stdlib.h>
 
 extern char *find_mount_point (char const *, struct stat const *)
-  _GL_ATTRIBUTE_MALLOC _GL_ATTRIBUTE_DEALLOC_FREE;
+  _GL_ATTRIBUTE_MALLOC _GL_ATTRIBUTE_DEALLOC_FREE _GL_ATTRIBUTE_NONNULL ();

src/force-link.h

@@ -1,2 +1,4 @@
-extern int force_linkat (int, char const *, int, char const *, int, bool, int);
-extern int force_symlinkat (char const *, int, char const *, bool, int);
+extern int force_linkat (int, char const *, int, char const *, int, bool, int)
+  _GL_ATTRIBUTE_NONNULL ();
+extern int force_symlinkat (char const *, int, char const *, bool, int)
+  _GL_ATTRIBUTE_NONNULL ();

src/operand2sig.h

@@ -15,4 +15,5 @@
    You should have received a copy of the GNU General Public License
    along with this program.  If not, see <https://www.gnu.org/licenses/>.  */
 
-extern int operand2sig (char const *operand, char *signame);
+extern int operand2sig (char const *operand, char *signame)
+  _GL_ATTRIBUTE_NONNULL ();

src/prog-fprintf.h

@@ -20,6 +20,6 @@
 # include <stdio.h>
 
 extern void prog_fprintf (FILE *fp, char const *fmt, ...)
-  _GL_ATTRIBUTE_FORMAT ((__printf__, 2, 3));
+  _GL_ATTRIBUTE_FORMAT ((__printf__, 2, 3)) _GL_ATTRIBUTE_NONNULL ((1, 2));;
 
 #endif