1/* Common extra functions.
2 Copyright (C) 2016-2022 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. */
42void write_message (const char *message) __attribute__ ((nonnull (1)));
43
44/* Avoid all the buffer overflow messages on stderr. */
45void ignore_stderr (void);
46
47/* Set fortification error handler. Used when tests want to verify that bad
48 code is caught by the library. */
49void 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. */
53void 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. */
61void *support_shared_allocate (size_t size);
62
63/* Deallocate a pointer returned by support_shared_allocate. */
64void 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. */
69void 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). */
75char *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). */
81char *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). */
86char *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. */
92int support_descriptor_supports_holes (int fd);
93
94/* Error-checking wrapper functions which terminate the process on
95 error. */
96
97extern void *xmalloc (size_t n)
98 __attribute_malloc__ __attribute_alloc_size__ ((1)) __attr_dealloc_free
99 __returns_nonnull;
100extern void *xcalloc (size_t n, size_t s)
101 __attribute_malloc__ __attribute_alloc_size__ ((1, 2)) __attr_dealloc_free
102 __returns_nonnull;
103extern void *xrealloc (void *o, size_t n)
104 __attribute_malloc__ __attribute_alloc_size__ ((2)) __attr_dealloc_free;
105extern char *xstrdup (const char *) __attribute_malloc__ __attr_dealloc_free
106 __returns_nonnull;
107void *xposix_memalign (size_t alignment, size_t n)
108 __attribute_malloc__ __attribute_alloc_align__ ((1))
109 __attribute_alloc_size__ ((2)) __attr_dealloc_free __returns_nonnull;
110char *xasprintf (const char *format, ...)
111 __attribute__ ((format (printf, 1, 2), malloc)) __attr_dealloc_free
112 __returns_nonnull;
113char *xstrdup (const char *) __attr_dealloc_free __returns_nonnull;
114char *xstrndup (const char *, size_t) __attr_dealloc_free __returns_nonnull;
115char *xsetlocale (int category, const char *locale);
116locale_t xnewlocale (int category_mask, const char *locale, locale_t base);
117char *xuselocale (locale_t newloc);
118
119/* These point to the TOP of the source/build tree, not your (or
120 support's) subdirectory. */
121extern const char support_srcdir_root[];
122extern const char support_objdir_root[];
123
124/* Corresponds to the path to the runtime linker used by the testsuite,
125 e.g. OBJDIR_PATH/elf/ld-linux-x86-64.so.2 */
126extern const char support_objdir_elf_ldso[];
127
128/* Corresponds to the --prefix= passed to configure. */
129extern const char support_install_prefix[];
130/* Corresponds to the install's lib/ or lib64/ directory. */
131extern const char support_libdir_prefix[];
132/* Corresponds to the install's bin/ directory. */
133extern const char support_bindir_prefix[];
134/* Corresponds to the install's sbin/ directory. */
135extern const char support_sbindir_prefix[];
136/* Corresponds to the install's system /lib or /lib64 directory. */
137extern const char support_slibdir_prefix[];
138/* Corresponds to the install's sbin/ directory (without prefix). */
139extern const char support_install_rootsbindir[];
140/* Corresponds to the install's compiled locale directory. */
141extern const char support_complocaledir_prefix[];
142
143/* Copies the file at the path FROM to TO. If TO does not exist, it
144 is created. If TO is a regular file, it is truncated before
145 copying. The file mode is copied, but the permissions are not. */
146extern void support_copy_file (const char *from, const char *to);
147
148extern ssize_t support_copy_file_range (int, off64_t *, int, off64_t *,
149 size_t, unsigned int);
150
151/* Return true if PATH supports 64-bit time_t interfaces for file
152 operations (such as fstatat or utimensat). */
153extern bool support_path_support_time64_value (const char *path, int64_t at,
154 int64_t mt);
155static __inline bool support_path_support_time64 (const char *path)
156{
157 /* 1s and 2s after y2038 limit. */
158 return support_path_support_time64_value (path, 0x80000001ULL,
159 0x80000002ULL);
160}
161
162/* Return true if the setitimer and getitimer syscalls support 64-bit time_t
163 values without resulting in overflow. This is not true on some linux systems
164 which have 64-bit time_t due to legacy kernel API's. */
165static __inline bool support_itimer_support_time64 (void)
166{
167#ifdef __KERNEL_OLD_TIMEVAL_MATCHES_TIMEVAL64
168 return __KERNEL_OLD_TIMEVAL_MATCHES_TIMEVAL64;
169#else
170 return sizeof (__time_t) == 8;
171#endif
172}
173
174/* Return true if stat supports nanoseconds resolution. PATH is used
175 for tests and its ctime may change. */
176extern bool support_stat_nanoseconds (const char *path);
177
178/* Return true if select modify the timeout to reflect the amount of time
179 no slept. */
180extern bool support_select_modifies_timeout (void);
181
182/* Return true if select normalize the timeout input by taking in account
183 tv_usec larger than 1000000. */
184extern bool support_select_normalizes_timeout (void);
185
186/* Return true if socket FD supports 64-bit timestamps with the SOL_SOCKET
187 and SO_TIMESTAMP/SO_TIMESTAMPNS. */
188extern bool support_socket_so_timestamp_time64 (int fd);
189
190/* Create a timer that trigger after SEC seconds and NSEC nanoseconds. If
191 REPEAT is true the timer will repeat indefinitely. If CALLBACK is not
192 NULL, the function will be called when the timer expires; otherwise a
193 dummy empty function is used instead.
194 This is implemented with POSIX per-process timer with SIGEV_SIGNAL. */
195timer_t support_create_timer (uint64_t sec, long int nsec, bool repeat,
196 void (*callback)(int));
197/* Disable the timer TIMER. */
198void support_delete_timer (timer_t timer);
199
200/* Wait until all threads except the current thread have exited (as
201 far as the kernel is concerned). */
202void support_wait_for_thread_exit (void);
203
204struct support_stack
205{
206 void *stack;
207 size_t size;
208 size_t guardsize;
209};
210
211/* Allocate stack suitable to used with xclone or sigaltstack call. The stack
212 will have a minimum size of SIZE + MINSIGSTKSZ bytes, rounded up to a whole
213 number of pages. There will be a large (at least 1 MiB) inaccessible guard
214 bands on either side of it.
215 The returned value on ALLOC_BASE and ALLOC_SIZE will be the usable stack
216 region, excluding the GUARD_SIZE allocated area.
217 It also terminates the process on error. */
218struct support_stack support_stack_alloc (size_t size);
219
220/* Deallocate the STACK. */
221void support_stack_free (struct support_stack *stack);
222
223
224/* Create a range of NUM opened '/dev/null' file descriptors using FLAGS and
225 MODE. The function takes care of restarting the open range if a file
226 descriptor is found within the specified range and also increases
227 RLIMIT_NOFILE if required.
228 The returned value is the lowest file descriptor number. */
229int support_open_dev_null_range (int num, int flags, mode_t mode);
230
231__END_DECLS
232
233#endif /* SUPPORT_H */
234