CoCalc -- sudo

GitHub Repository: sudo-project/sudo
Path: blob/main/include/sudo_util.h
¹⁵³² views
1
/*
2
 * SPDX-License-Identifier: ISC
3
 *
4
 * Copyright (c) 2013-2025 Todd C. Miller <[email protected]>
5
 *
6
 * Permission to use, copy, modify, and distribute this software for any
7
 * purpose with or without fee is hereby granted, provided that the above
8
 * copyright notice and this permission notice appear in all copies.
9
 *
10
 * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
11
 * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
12
 * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
13
 * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
14
 * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
15
 * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
16
 * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
17
 */
18

19
#ifndef SUDO_UTIL_H
20
#define SUDO_UTIL_H
21

22
#include <sys/types.h>	/* for dev_t, mode_t, gid_t, size_t, ssize_t, uid_t */
23
#ifdef HAVE_STDBOOL_H
24
# include <stdbool.h>
25
#else
26
# include <compat/stdbool.h>
27
#endif /* HAVE_STDBOOL_H */
28

29
#ifdef __TANDEM
30
# define ROOT_UID	65535
31
#else
32
# define ROOT_UID	0
33
#endif
34
#define ROOT_GID	0
35

36
#ifndef OFF_T_MAX
37
# if SIZEOF_OFF_T == 8
38
#  define OFF_T_MAX	LLONG_MAX
39
# else
40
#  define OFF_T_MAX	INT_MAX
41
# endif
42
#endif
43

44
#ifndef TIME_T_MIN
45
# if SIZEOF_TIME_T == 8
46
#  define TIME_T_MIN	LLONG_MIN
47
# else
48
#  define TIME_T_MIN	INT_MIN
49
# endif
50
#endif
51
#ifndef TIME_T_MAX
52
# if SIZEOF_TIME_T == 8
53
#  define TIME_T_MAX	LLONG_MAX
54
# else
55
#  define TIME_T_MAX	INT_MAX
56
# endif
57
#endif
58

59
/*
60
 * Macros for operating on struct timespec.
61
 */
62
#define sudo_timespecclear(ts)	((ts)->tv_sec = (ts)->tv_nsec = 0)
63

64
#define sudo_timespecisset(ts)	((ts)->tv_sec || (ts)->tv_nsec)
65

66
#define sudo_timespeccmp(ts1, ts2, op)					       \
67
    (((ts1)->tv_sec == (ts2)->tv_sec) ?					       \
68
	((ts1)->tv_nsec op (ts2)->tv_nsec) :				       \
69
	((ts1)->tv_sec op (ts2)->tv_sec))
70

71
#define sudo_timespecadd(ts1, ts2, ts3)					       \
72
    do {								       \
73
	(ts3)->tv_sec = (ts1)->tv_sec + (ts2)->tv_sec;			       \
74
	(ts3)->tv_nsec = (ts1)->tv_nsec + (ts2)->tv_nsec;		       \
75
	while ((ts3)->tv_nsec >= 1000000000) {				       \
76
	    (ts3)->tv_sec++;						       \
77
	    (ts3)->tv_nsec -= 1000000000;				       \
78
	}								       \
79
    } while (0)
80

81
#define sudo_timespecsub(ts1, ts2, ts3)					       \
82
    do {								       \
83
	(ts3)->tv_sec = (ts1)->tv_sec - (ts2)->tv_sec;			       \
84
	(ts3)->tv_nsec = (ts1)->tv_nsec - (ts2)->tv_nsec;		       \
85
	while ((ts3)->tv_nsec < 0) {					       \
86
	    (ts3)->tv_sec--;						       \
87
	    (ts3)->tv_nsec += 1000000000;				       \
88
	}								       \
89
    } while (0)
90

91
#ifndef TIMEVAL_TO_TIMESPEC
92
# define TIMEVAL_TO_TIMESPEC(tv, ts)					       \
93
    do {								       \
94
	(ts)->tv_sec = (tv)->tv_sec;					       \
95
	(ts)->tv_nsec = (tv)->tv_usec * 1000;				       \
96
    } while (0)
97
#endif
98

99
#ifndef TIMESPEC_TO_TIMEVAL
100
# define TIMESPEC_TO_TIMEVAL(tv, ts)					       \
101
    do {								       \
102
	(tv)->tv_sec = (ts)->tv_sec;					       \
103
	(tv)->tv_usec = (ts)->tv_nsec / 1000;				       \
104
    } while (0)
105
#endif
106

107
/*
108
 * The timespec version of st_mtime may vary on different platforms.
109
 */
110
#if defined(HAVE_ST_MTIM)
111
# if defined(HAVE_ST__TIM)
112
#  define SUDO_ST_MTIM		st_mtim.st__tim
113
# else
114
#  define SUDO_ST_MTIM		st_mtim
115
# endif
116
#elif defined(HAVE_ST_MTIMESPEC)
117
# define SUDO_ST_MTIM		st_mtimespec
118
#endif
119

120
/*
121
 * Macro to extract mtime as timespec.
122
 * If there is no way to set the timestamp using nanosecond precision,
123
 * we only fetch microsecond precision.  Otherwise there is a mismatch
124
 * between the timestamp we read and the one we wrote.
125
 */
126
#if defined(SUDO_ST_MTIM)
127
# if defined(HAVE_FUTIMENS) && defined(HAVE_UTIMENSAT)
128
#  define mtim_get(_x, _y)	do { (_y).tv_sec = (_x)->SUDO_ST_MTIM.tv_sec; (_y).tv_nsec = (_x)->SUDO_ST_MTIM.tv_nsec; } while (0)
129
# else
130
#  define mtim_get(_x, _y)	do { (_y).tv_sec = (_x)->SUDO_ST_MTIM.tv_sec; (_y).tv_nsec = ((_x)->SUDO_ST_MTIM.tv_nsec / 1000) * 1000; } while (0)
131
# endif
132
#elif defined(HAVE_ST_NMTIME)
133
# define mtim_get(_x, _y)	do { (_y).tv_sec = (_x)->st_mtime; (_y).tv_nsec = (_x)->st_nmtime; } while (0)
134
#else
135
# define mtim_get(_x, _y)	do { (_y).tv_sec = (_x)->st_mtime; (_y).tv_nsec = 0; } while (0)
136
#endif /* HAVE_ST_MTIM */
137

138
/* sizeof() that returns a signed value */
139
#define ssizeof(_x)	((ssize_t)sizeof(_x))
140

141
/* Bit map macros. */
142
#define sudo_setbit(_a, _i) ((_a)[(_i) / NBBY] |= 1U << ((_i) % NBBY))
143
#define sudo_clrbit(_a, _i) ((_a)[(_i) / NBBY] &= ~(1U << ((_i) % NBBY)))
144
#define sudo_isset(_a, _i)  ((_a)[(_i) / NBBY] & (1U << ((_i) % NBBY)))
145
#define sudo_isclr(_a, _i)  (((_a)[(_i) / NBBY] & (1U << ((_i) % NBBY))) == 0)
146

147
/* Macros to determine the length of a type in string form. */
148
#define STRLEN_MAX_UNSIGNED(t)	(((sizeof(t) * 8 * 1233) >> 12) + 1)
149
#define STRLEN_MAX_SIGNED(t)	(STRLEN_MAX_UNSIGNED(t) + ((sizeof(t) == 8) ? 0 : 1))
150

151
/* sudo_parseln() flags */
152
#define PARSELN_COMM_BOL	0x01	/* comments only at beginning of line */
153
#define PARSELN_CONT_IGN	0x02	/* ignore line continuation char */
154

155
/*
156
 * Macros to quiet gcc's warn_unused_result attribute.
157
 */
158
#ifdef __GNUC__
159
# define ignore_result(x) do {						       \
160
    __typeof__(x) y = (x);						       \
161
    (void)y;								       \
162
} while(0)
163
#else
164
# define ignore_result(x)	(void)(x)
165
#endif
166

167
/* Forward struct declarations. */
168
struct stat;
169

170
/* aix.c */
171
sudo_dso_public int aix_getauthregistry_v1(char *user, char *saved_registry);
172
#define aix_getauthregistry(_a, _b) aix_getauthregistry_v1((_a), (_b))
173
sudo_dso_public int aix_prep_user_v1(char *user, const char *tty);
174
#define aix_prep_user(_a, _b) aix_prep_user_v1((_a), (_b))
175
sudo_dso_public int aix_restoreauthdb_v1(void);
176
#define aix_restoreauthdb() aix_restoreauthdb_v1()
177
sudo_dso_public int aix_setauthdb_v1(char *user);
178
sudo_dso_public int aix_setauthdb_v2(char *user, char *registry);
179
#define aix_setauthdb(_a, _b) aix_setauthdb_v2((_a), (_b))
180

181
/* base64.c */
182
sudo_dso_public size_t sudo_base64_decode_v1(const char * restrict str, unsigned char * restrict dst, size_t dsize);
183
#define sudo_base64_decode(_a, _b, _c) sudo_base64_decode_v1((_a), (_b), (_c))
184
sudo_dso_public size_t sudo_base64_encode_v1(const unsigned char * restrict in, size_t in_len, char * restrict out, size_t out_len);
185
#define sudo_base64_encode(_a, _b, _c, _d) sudo_base64_encode_v1((_a), (_b), (_c), (_d))
186

187
/* basename.c */
188
sudo_dso_public char *sudo_basename_v1(const char *filename);
189
#define sudo_basename(_a) sudo_basename_v1(_a)
190

191
/* gethostname.c */
192
sudo_dso_public char *sudo_gethostname_v1(void);
193
#define sudo_gethostname() sudo_gethostname_v1()
194
sudo_dso_public size_t sudo_host_name_max_v1(void);
195
#define sudo_host_name_max() sudo_host_name_max_v1()
196

197
/* gettime.c */
198
sudo_dso_public int sudo_gettime_awake_v1(struct timespec *ts);
199
#define sudo_gettime_awake(_a) sudo_gettime_awake_v1((_a))
200
sudo_dso_public int sudo_gettime_mono_v1(struct timespec *ts);
201
#define sudo_gettime_mono(_a) sudo_gettime_mono_v1((_a))
202
sudo_dso_public int sudo_gettime_real_v1(struct timespec *ts);
203
#define sudo_gettime_real(_a) sudo_gettime_real_v1((_a))
204

205
/* gidlist.c */
206
sudo_dso_public int sudo_parse_gids_v1(const char *gidstr, const gid_t *basegid, GETGROUPS_T **gidsp);
207
#define sudo_parse_gids(_a, _b, _c) sudo_parse_gids_v1((_a), (_b), (_c))
208

209
/* getgrouplist.c */
210
sudo_dso_public int sudo_getgrouplist2_v1(const char *name, gid_t basegid, GETGROUPS_T **groupsp, int *ngroupsp);
211
#define sudo_getgrouplist2(_a, _b, _c, _d) sudo_getgrouplist2_v1((_a), (_b), (_c), (_d))
212

213
/* hexchar.c */
214
sudo_dso_public int sudo_hexchar_v1(const char s[restrict static 2]);
215
#define sudo_hexchar(_a) sudo_hexchar_v1(_a)
216

217
/* key_val.c */
218
sudo_dso_public char *sudo_new_key_val_v1(const char *key, const char *value);
219
#define sudo_new_key_val(_a, _b) sudo_new_key_val_v1((_a), (_b))
220

221
/* locking.c */
222
#define SUDO_LOCK	1		/* lock a file */
223
#define SUDO_TLOCK	2		/* test & lock a file (non-blocking) */
224
#define SUDO_UNLOCK	4		/* unlock a file */
225
sudo_dso_public bool sudo_lock_file_v1(int fd, int action);
226
#define sudo_lock_file(_a, _b) sudo_lock_file_v1((_a), (_b))
227
sudo_dso_public bool sudo_lock_region_v1(int fd, int action, off_t len);
228
#define sudo_lock_region(_a, _b, _c) sudo_lock_region_v1((_a), (_b), (_c))
229

230
/* logfac.c */
231
sudo_dso_public bool sudo_str2logfac_v1(const char *str, int *logfac);
232
#define sudo_str2logfac(_a, _b) sudo_str2logfac_v1((_a), (_b))
233
sudo_dso_public const char *sudo_logfac2str_v1(int num);
234
#define sudo_logfac2str(_a) sudo_logfac2str_v1((_a))
235

236
/* login_max.c */
237
sudo_dso_public size_t sudo_login_name_max_v1(void);
238
#define sudo_login_name_max() sudo_login_name_max_v1()
239

240
/* logpri.c */
241
sudo_dso_public bool sudo_str2logpri_v1(const char *str, int *logpri);
242
#define sudo_str2logpri(_a, _b) sudo_str2logpri_v1((_a), (_b))
243
sudo_dso_public const char *sudo_logpri2str_v1(int num);
244
#define sudo_logpri2str(_a) sudo_logpri2str_v1((_a))
245

246
/* mkdir_parents.c */
247
sudo_dso_public bool sudo_mkdir_parents_v1(const char *path, uid_t uid, gid_t gid, mode_t mode, bool quiet);
248
#define sudo_mkdir_parents(_a, _b, _c, _d, _e) sudo_mkdir_parents_v1((_a), (_b), (_c), (_d), (_e))
249
sudo_dso_public int sudo_open_parent_dir_v1(const char *path, uid_t uid, gid_t gid, mode_t mode, bool quiet);
250
#define sudo_open_parent_dir(_a, _b, _c, _d, _e) sudo_open_parent_dir_v1((_a), (_b), (_c), (_d), (_e))
251

252
/* mmap_alloc.c */
253
sudo_dso_public void *sudo_mmap_alloc_v1(size_t size) sudo_malloclike;
254
#define sudo_mmap_alloc(_a) sudo_mmap_alloc_v1(_a)
255
sudo_dso_public void *sudo_mmap_allocarray_v1(size_t count, size_t size) sudo_malloclike;
256
#define sudo_mmap_allocarray(_a, _b) sudo_mmap_allocarray_v1((_a), (_b))
257
sudo_dso_public char *sudo_mmap_strdup_v1(const char *str);
258
#define sudo_mmap_strdup(_a) sudo_mmap_strdup_v1(_a)
259
sudo_dso_public void sudo_mmap_free_v1(void *ptr);
260
#define sudo_mmap_free(_a) sudo_mmap_free_v1(_a)
261
sudo_dso_public int sudo_mmap_protect_v1(void *ptr);
262
#define sudo_mmap_protect(_a) sudo_mmap_protect_v1(_a)
263

264
/* multiarch.c */
265
sudo_dso_public char *sudo_stat_multiarch_v1(const char * restrict path, struct stat * restrict sb);
266
#define sudo_stat_multiarch(_a, _b) sudo_stat_multiarch_v1((_a), (_b))
267

268
/* parseln.c */
269
sudo_dso_public ssize_t sudo_parseln_v1(char **buf, size_t *bufsize, unsigned int *lineno, FILE *fp);
270
sudo_dso_public ssize_t sudo_parseln_v2(char **buf, size_t *bufsize, unsigned int *lineno, FILE *fp, int flags);
271
#define sudo_parseln(_a, _b, _c, _d, _e) sudo_parseln_v2((_a), (_b), (_c), (_d), (_e))
272

273
/* progname.c */
274
sudo_dso_public void initprogname(const char *);
275
sudo_dso_public void initprogname2(const char *, const char * const *);
276

277
/* rcstr.c */
278
sudo_dso_public char *sudo_rcstr_dup(const char *src);
279
sudo_dso_public char *sudo_rcstr_alloc(size_t len) sudo_malloclike;
280
sudo_dso_public char *sudo_rcstr_addref(const char *s);
281
sudo_dso_public void sudo_rcstr_delref(const char *s);
282

283
/* regex.c */
284
sudo_dso_public bool sudo_regex_compile_v1(void *v, const char *pattern, const char **errstr);
285
#define sudo_regex_compile(_a, _b, _c) sudo_regex_compile_v1((_a), (_b), (_c))
286

287
/* roundup.c */
288
sudo_dso_public unsigned int sudo_pow2_roundup_v1(unsigned int len);
289
sudo_dso_public size_t sudo_pow2_roundup_v2(size_t len);
290
#define sudo_pow2_roundup(_a) sudo_pow2_roundup_v2((_a))
291

292
/* secure_path.c */
293
#define SUDO_PATH_SECURE		0
294
#define SUDO_PATH_MISSING		-1
295
#define SUDO_PATH_BAD_TYPE		-2
296
#define SUDO_PATH_WRONG_OWNER		-3
297
#define SUDO_PATH_WORLD_WRITABLE	-4
298
#define SUDO_PATH_GROUP_WRITABLE	-5
299
sudo_dso_public int sudo_secure_dir_v1(const char *path, uid_t uid, gid_t gid, struct stat *sb);
300
#define sudo_secure_dir(_a, _b, _c, _d) sudo_secure_dir_v1((_a), (_b), (_c), (_d))
301
sudo_dso_public int sudo_secure_fd_v1(int fd, unsigned int type, uid_t uid, gid_t gid, struct stat *sb);
302
#define sudo_secure_fd(_a, _b, _c, _d, _e) sudo_secure_fd_v1((_a), (_b), (_c), (_d), (_e))
303
sudo_dso_public int sudo_secure_file_v1(const char *path, uid_t uid, gid_t gid, struct stat *sb);
304
#define sudo_secure_file(_a, _b, _c, _d) sudo_secure_file_v1((_a), (_b), (_c), (_d))
305
sudo_dso_public int sudo_secure_open_file_v1(const char *path, uid_t uid, gid_t gid, struct stat *sb, int *error);
306
#define sudo_secure_open_file(_a, _b, _c, _d, _e) sudo_secure_open_file_v1((_a), (_b), (_c), (_d), (_e))
307
sudo_dso_public int sudo_secure_open_dir_v1(const char *path, uid_t uid, gid_t gid, struct stat *sb, int *error);
308
#define sudo_secure_open_dir(_a, _b, _c, _d, _e) sudo_secure_open_dir_v1((_a), (_b), (_c), (_d), (_e))
309
sudo_dso_public int sudo_open_conf_path_v1(const char *path, char *name, size_t namesize, int (*fn)(const char *, int));
310
#define sudo_open_conf_path(_a, _b, _c, _d) sudo_open_conf_path_v1((_a), (_b), (_c), (_d))
311

312
/* setgroups.c */
313
sudo_dso_public int sudo_setgroups_v1(int ngids, const GETGROUPS_T *gids);
314
#define sudo_setgroups(_a, _b) sudo_setgroups_v1((_a), (_b))
315

316
/* strsplit.c */
317
sudo_dso_public const char *sudo_strsplit_v1(const char *str, const char *endstr, const char *sep, const char **last);
318
#define sudo_strsplit(_a, _b, _c, _d) sudo_strsplit_v1(_a, _b, _c, _d)
319

320
/* strtobool.c */
321
sudo_dso_public int sudo_strtobool_v1(const char *str);
322
#define sudo_strtobool(_a) sudo_strtobool_v1((_a))
323

324
/* strtonum.c */
325
/* Not versioned for historical reasons. */
326
sudo_dso_public long long sudo_strtonum(const char *, long long, long long, const char **);
327
/* Not currently exported. */
328
long long sudo_strtonumx(const char *str, long long minval, long long maxval, char **endp, const char **errstrp);
329

330
/* strtoid.c */
331
sudo_dso_public id_t sudo_strtoid_v1(const char *str, const char *sep, char **endp, const char **errstr);
332
sudo_dso_public id_t sudo_strtoid_v2(const char *str, const char **errstr);
333
#define sudo_strtoid(_a, _b) sudo_strtoid_v2((_a), (_b))
334
sudo_dso_public id_t sudo_strtoidx_v1(const char *str, const char *sep, char **endp, const char **errstr);
335
#define sudo_strtoidx(_a, _b, _c, _d) sudo_strtoidx_v1((_a), (_b), (_c), (_d))
336

337
/* strtomode.c */
338
sudo_dso_public int sudo_strtomode_v1(const char *cp, const char **errstr);
339
sudo_dso_public mode_t sudo_strtomode_v2(const char *cp, const char **errstr);
340
#define sudo_strtomode(_a, _b) sudo_strtomode_v2((_a), (_b))
341

342
/* sudo_printf.c */
343
extern int (*sudo_printf)(int msg_type, const char * restrict fmt, ...);
344

345
/* term.c */
346
#define SUDO_TERM_ISIG	0x01U
347
#define SUDO_TERM_OFLAG	0x02U
348
sudo_dso_public bool sudo_isatty_v1(int fd, struct stat *sbp);
349
#define sudo_isatty(_a, _b) sudo_isatty_v1((_a), (_b))
350
sudo_dso_public bool sudo_term_cbreak_v1(int fd);
351
sudo_dso_public bool sudo_term_cbreak_v2(int fd, bool flush);
352
#define sudo_term_cbreak(_a, _b) sudo_term_cbreak_v2((_a), (_b))
353
sudo_dso_public bool sudo_term_copy_v1(int src, int dst);
354
#define sudo_term_copy(_a, _b) sudo_term_copy_v1((_a), (_b))
355
sudo_dso_public bool sudo_term_noecho_v1(int fd);
356
#define sudo_term_noecho(_a) sudo_term_noecho_v1((_a))
357
sudo_dso_public bool sudo_term_raw_v1(int fd, unsigned int flags);
358
#define sudo_term_raw(_a, _b) sudo_term_raw_v1((_a), (_b))
359
sudo_dso_public bool sudo_term_restore_v1(int fd, bool flush);
360
#define sudo_term_restore(_a, _b) sudo_term_restore_v1((_a), (_b))
361
sudo_dso_public bool sudo_term_is_raw_v1(int fd);
362
#define sudo_term_is_raw(_a) sudo_term_is_raw_v1((_a))
363

364
/* ttyname_dev.c */
365
sudo_dso_public char *sudo_ttyname_dev_v1(dev_t tdev, char *name, size_t namelen);
366
#define sudo_ttyname_dev(_a, _b, _c) sudo_ttyname_dev_v1((_a), (_b), (_c))
367

368
/* ttysize.c */
369
sudo_dso_public void sudo_get_ttysize_v1(int *rowp, int *colp);
370
sudo_dso_public void sudo_get_ttysize_v2(int fd, int *rowp, int *colp);
371
#define sudo_get_ttysize(_a, _b, _c) sudo_get_ttysize_v2((_a), (_b), (_c))
372

373
/* uuid.c */
374
sudo_dso_public void sudo_uuid_create_v1(unsigned char uuid_out[restrict static 16]);
375
#define sudo_uuid_create(_a) sudo_uuid_create_v1((_a))
376
sudo_dso_public char *sudo_uuid_to_string_v1(const unsigned char uuid[restrict static 16], char * restrict dst, size_t dstsiz);
377
#define sudo_uuid_to_string(_a, _b, _c) sudo_uuid_to_string_v1((_a), (_b), (_c))
378
sudo_dso_public int sudo_uuid_from_string_v1(const char *str, unsigned char uuid[restrict static 16]);
379
#define sudo_uuid_from_string(_a, _b) sudo_uuid_from_string_v1((_a), (_b))
380

381
#endif /* SUDO_UTIL_H */
382

383
Product

Resources

Company
