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. */
41void write_message (const char *message) __attribute__ ((nonnull (1)));
42
43/* Avoid all the buffer overflow messages on stderr. */
44void ignore_stderr (void);
45
46/* Set fortification error handler. Used when tests want to verify that bad
47 code is caught by the library. */
48void 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. */
52void 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. */
60void *support_shared_allocate (size_t size);
61
62/* Deallocate a pointer returned by support_shared_allocate. */
63void 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. */
68void 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). */
74char *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). */
79char *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. */
85int support_descriptor_supports_holes (int fd);
86
87/* Error-checking wrapper functions which terminate the process on
88 error. */
89
90extern void *xmalloc (size_t n)
91 __attribute_malloc__ __attribute_alloc_size__ ((1)) __attr_dealloc_free
92 __returns_nonnull;
93extern void *xcalloc (size_t n, size_t s)
94 __attribute_malloc__ __attribute_alloc_size__ ((1, 2)) __attr_dealloc_free
95 __returns_nonnull;
96extern void *xrealloc (void *o, size_t n)
97 __attribute_malloc__ __attribute_alloc_size__ ((2)) __attr_dealloc_free;
98extern char *xstrdup (const char *) __attribute_malloc__ __attr_dealloc_free
99 __returns_nonnull;
100void *xposix_memalign (size_t alignment, size_t n)
101 __attribute_malloc__ __attribute_alloc_size__ ((2)) __attr_dealloc_free
102 __returns_nonnull;
103char *xasprintf (const char *format, ...)
104 __attribute__ ((format (printf, 1, 2), malloc)) __attr_dealloc_free
105 __returns_nonnull;
106char *xstrdup (const char *) __attr_dealloc_free __returns_nonnull;
107char *xstrndup (const char *, size_t) __attr_dealloc_free __returns_nonnull;
108char *xsetlocale (int category, const char *locale);
109locale_t xnewlocale (int category_mask, const char *locale, locale_t base);
110char *xuselocale (locale_t newloc);
111
112/* These point to the TOP of the source/build tree, not your (or
113 support's) subdirectory. */
114extern const char support_srcdir_root[];
115extern const char support_objdir_root[];
116
117/* Corresponds to the path to the runtime linker used by the testsuite,
118 e.g. OBJDIR_PATH/elf/ld-linux-x86-64.so.2 */
119extern const char support_objdir_elf_ldso[];
120
121/* Corresponds to the --prefix= passed to configure. */
122extern const char support_install_prefix[];
123/* Corresponds to the install's lib/ or lib64/ directory. */
124extern const char support_libdir_prefix[];
125/* Corresponds to the install's bin/ directory. */
126extern const char support_bindir_prefix[];
127/* Corresponds to the install's sbin/ directory. */
128extern const char support_sbindir_prefix[];
129/* Corresponds to the install's system /lib or /lib64 directory. */
130extern const char support_slibdir_prefix[];
131/* Corresponds to the install's sbin/ directory (without prefix). */
132extern const char support_install_rootsbindir[];
133/* Corresponds to the install's compiled locale directory. */
134extern const char support_complocaledir_prefix[];
135
136/* Copies the file at the path FROM to TO. If TO does not exist, it
137 is created. If TO is a regular file, it is truncated before
138 copying. The file mode is copied, but the permissions are not. */
139extern void support_copy_file (const char *from, const char *to);
140
141extern ssize_t support_copy_file_range (int, off64_t *, int, off64_t *,
142 size_t, unsigned int);
143
144/* Return true if PATH supports 64-bit time_t interfaces for file
145 operations (such as fstatat or utimensat). */
146extern bool support_path_support_time64_value (const char *path, int64_t at,
147 int64_t mt);
148static __inline bool support_path_support_time64 (const char *path)
149{
150 /* 1s and 2s after y2038 limit. */
151 return support_path_support_time64_value (path, 0x80000001ULL,
152 0x80000002ULL);
153}
154
155/* Return true if stat supports nanoseconds resolution. PATH is used
156 for tests and its ctime may change. */
157extern bool support_stat_nanoseconds (const char *path);
158
159/* Return true if select modify the timeout to reflect the amount of time
160 no slept. */
161extern bool support_select_modifies_timeout (void);
162
163/* Return true if select normalize the timeout input by taking in account
164 tv_usec larger than 1000000. */
165extern bool support_select_normalizes_timeout (void);
166
167/* Create a timer that trigger after SEC seconds and NSEC nanoseconds. If
168 REPEAT is true the timer will repeat indefinitely. If CALLBACK is not
169 NULL, the function will be called when the timer expires; otherwise a
170 dummy empty function is used instead.
171 This is implemented with POSIX per-process timer with SIGEV_SIGNAL. */
172timer_t support_create_timer (uint64_t sec, long int nsec, bool repeat,
173 void (*callback)(int));
174/* Disable the timer TIMER. */
175void support_delete_timer (timer_t timer);
176
177struct support_stack
178{
179 void *stack;
180 size_t size;
181 size_t guardsize;
182};
183
184/* Allocate stack suitable to used with xclone or sigaltstack call. The stack
185 will have a minimum size of SIZE + MINSIGSTKSZ bytes, rounded up to a whole
186 number of pages. There will be a large (at least 1 MiB) inaccessible guard
187 bands on either side of it.
188 The returned value on ALLOC_BASE and ALLOC_SIZE will be the usable stack
189 region, excluding the GUARD_SIZE allocated area.
190 It also terminates the process on error. */
191struct support_stack support_stack_alloc (size_t size);
192
193/* Deallocate the STACK. */
194void support_stack_free (struct support_stack *stack);
195
196__END_DECLS
197
198#endif /* SUPPORT_H */
199