support/support.h

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