support/support.h

   1 /* Common extra functions.
   2    Copyright (C) 2016-2021 Free Software Foundation, Inc.
   3    This file is part of the GNU C Library.
   4
   5    The GNU C Library is free software; you can redistribute it and/or
   6    modify it under the terms of the GNU Lesser General Public
   7    License as published by the Free Software Foundation; either
   8    version 2.1 of the License, or (at your option) any later version.
   9
  10    The GNU C Library is distributed in the hope that it will be useful,
  11    but WITHOUT ANY WARRANTY; without even the implied warranty of
  12    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13    Lesser General Public License for more details.
  14
  15    You should have received a copy of the GNU Lesser General Public
  16    License along with the GNU C Library; if not, see
  17    <https://www.gnu.org/licenses/>.  */
  18
  19 /* This header file should only contain definitions compatible with
  20    C90.  (Using __attribute__ is fine because <features.h> provides a
  21    fallback.)  */
  22
  23 #ifndef SUPPORT_H
  24 #define SUPPORT_H
  25
  26 #include <stdbool.h>
  27 #include <stdint.h>
  28 #include <stddef.h>
  29 #include <sys/cdefs.h>
  30 /* For mode_t.  */
  31 #include <sys/stat.h>
  32 /* For ssize_t and off64_t.  */
  33 #include <sys/types.h>
  34 /* For locale_t.  */
  35 #include <locale.h>
  36
  37 __BEGIN_DECLS
  38
  39 /* Write a message to standard output.  Can be used in signal
  40    handlers.  */
  41 void write_message (const char *message) __attribute__ ((nonnull (1)));
  42
  43 /* Avoid all the buffer overflow messages on stderr.  */
  44 void ignore_stderr (void);
  45
  46 /* Set fortification error handler.  Used when tests want to verify that bad
  47    code is caught by the library.  */
  48 void set_fortify_handler (void (*handler) (int sig));
  49
  50 /* Report an out-of-memory error for the allocation of SIZE bytes in
  51    FUNCTION, terminating the process.  */
  52 void oom_error (const char *function, size_t size)
  53   __attribute__ ((nonnull (1)));
  54
  55 /* Return a pointer to a memory region of SIZE bytes.  The memory is
  56    initialized to zero and will be shared with subprocesses (across
  57    fork).  The returned pointer must be freed using
  58    support_shared_free; it is not compatible with the malloc
  59    functions.  */
  60 void *support_shared_allocate (size_t size);
  61
  62 /* Deallocate a pointer returned by support_shared_allocate.  */
  63 void support_shared_free (void *);
  64
  65 /* Write CONTENTS to the file PATH.  Create or truncate the file as
  66    needed.  The file mode is 0666 masked by the umask.  Terminate the
  67    process on error.  */
  68 void support_write_file_string (const char *path, const char *contents);
  69
  70 /* Quote the contents of the byte array starting at BLOB, of LENGTH
  71    bytes, in such a way that the result string can be included in a C
  72    literal (in single/double quotes, without putting the quotes into
  73    the result).  */
  74 char *support_quote_blob (const void *blob, size_t length);
  75
  76 /* Quote the contents of the string, in such a way that the result
  77    string can be included in a C literal (in single/double quotes,
  78    without putting the quotes into the result).  */
  79 char *support_quote_string (const char *);
  80
  81 /* Returns non-zero if the file descriptor is a regular file on a file
  82    system which supports holes (that is, seeking and writing does not
  83    allocate storage for the range of zeros).  FD must refer to a
  84    regular file open for writing, and initially empty.  */
  85 int support_descriptor_supports_holes (int fd);
  86
  87 /* Error-checking wrapper functions which terminate the process on
  88    error.  */
  89
  90 void *xmalloc (size_t) __attribute__ ((malloc));
  91 void *xcalloc (size_t n, size_t s) __attribute__ ((malloc));
  92 void *xrealloc (void *p, size_t n);
  93 void *xposix_memalign (size_t alignment, size_t n);
  94 char *xasprintf (const char *format, ...)
  95   __attribute__ ((format (printf, 1, 2), malloc));
  96 char *xstrdup (const char *);
  97 char *xstrndup (const char *, size_t);
  98 char *xsetlocale (int category, const char *locale);
  99 locale_t xnewlocale (int category_mask, const char *locale, locale_t base);
 100 char *xuselocale (locale_t newloc);
 101
 102 /* These point to the TOP of the source/build tree, not your (or
 103    support's) subdirectory.  */
 104 extern const char support_srcdir_root[];
 105 extern const char support_objdir_root[];
 106
 107 /* Corresponds to the path to the runtime linker used by the testsuite,
 108    e.g. OBJDIR_PATH/elf/ld-linux-x86-64.so.2  */
 109 extern const char support_objdir_elf_ldso[];
 110
 111 /* Corresponds to the --prefix= passed to configure.  */
 112 extern const char support_install_prefix[];
 113 /* Corresponds to the install's lib/ or lib64/ directory.  */
 114 extern const char support_libdir_prefix[];
 115 /* Corresponds to the install's bin/ directory.  */
 116 extern const char support_bindir_prefix[];
 117 /* Corresponds to the install's sbin/ directory.  */
 118 extern const char support_sbindir_prefix[];
 119 /* Corresponds to the install's system /lib or /lib64 directory.  */
 120 extern const char support_slibdir_prefix[];
 121 /* Corresponds to the install's sbin/ directory (without prefix).  */
 122 extern const char support_install_rootsbindir[];
 123 /* Corresponds to the install's compiled locale directory.  */
 124 extern const char support_complocaledir_prefix[];
 125
 126 /* Copies the file at the path FROM to TO.  If TO does not exist, it
 127    is created.  If TO is a regular file, it is truncated before
 128    copying.  The file mode is copied, but the permissions are not.  */
 129 extern void support_copy_file (const char *from, const char *to);
 130
 131 extern ssize_t support_copy_file_range (int, off64_t *, int, off64_t *,
 132                                         size_t, unsigned int);
 133
 134 /* Return true if PATH supports 64-bit time_t interfaces for file
 135    operations (such as fstatat or utimensat).  */
 136 extern bool support_path_support_time64_value (const char *path, int64_t at,
 137                                                int64_t mt);
 138 static __inline bool support_path_support_time64 (const char *path)
 139 {
 140   /* 1s and 2s after y2038 limit.  */
 141   return support_path_support_time64_value (path, 0x80000001ULL,
 142                                             0x80000002ULL);
 143 }
 144
 145 /* Return true if stat supports nanoseconds resolution.  PATH is used
 146    for tests and its ctime may change.  */
 147 extern bool support_stat_nanoseconds (const char *path);
 148
 149 /* Return true if select modify the timeout to reflect the amount of time
 150    no slept.  */
 151 extern bool support_select_modifies_timeout (void);
 152
 153 /* Return true if select normalize the timeout input by taking in account
 154    tv_usec larger than 1000000.  */
 155 extern bool support_select_normalizes_timeout (void);
 156
 157 /* Create a timer that trigger after SEC seconds and NSEC nanoseconds.  If
 158    REPEAT is true the timer will repeat indefinitely.  If CALLBACK is not
 159    NULL, the function will be called when the timer expires; otherwise a
 160    dummy empty function is used instead.
 161    This is implemented with POSIX per-process timer with SIGEV_SIGNAL.  */
 162 timer_t support_create_timer (uint64_t sec, long int nsec, bool repeat,
 163                               void (*callback)(int));
 164 /* Disable the timer TIMER.  */
 165 void support_delete_timer (timer_t timer);
 166
 167 struct support_stack
 168 {
 169   void *stack;
 170   size_t size;
 171   size_t guardsize;
 172 };
 173
 174 /* Allocate stack suitable to used with xclone or sigaltstack call. The stack
 175    will have a minimum size of SIZE + MINSIGSTKSZ bytes, rounded up to a whole
 176    number of pages.  There will be a large (at least 1 MiB) inaccessible guard
 177    bands on either side of it.
 178    The returned value on ALLOC_BASE and ALLOC_SIZE will be the usable stack
 179    region, excluding the GUARD_SIZE allocated area.
 180    It also terminates the process on error.  */
 181 struct support_stack support_stack_alloc (size_t size);
 182
 183 /* Deallocate the STACK.  */
 184 void support_stack_free (struct support_stack *stack);
 185
 186 __END_DECLS
 187
 188 #endif /* SUPPORT_H */