BRL-CAD
Loading...
Searching...
No Matches
glob.h
Go to the documentation of this file.
1/* G L O B . H
2 * BRL-CAD
3 *
4 * Copyright (c) 2015-2025 United States Government as represented by
5 * the U.S. Army Research Laboratory.
6 *
7 * This library is free software; you can redistribute it and/or
8 * modify it under the terms of the GNU Lesser General Public License
9 * version 2.1 as published by the Free Software Foundation.
10 *
11 * This library is distributed in the hope that it will be useful, but
12 * 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 this file; see the file named COPYING for more
18 * information.
19 */
20
21#ifndef BU_GLOB_H
22#define BU_GLOB_H
23
24#include "common.h"
25
26#include "bu/defines.h"
27#include "bu/vls.h"
28
30
31
32/** @addtogroup bu_experimental
33 *
34 * NOTE - the glob API below is a work in progress - until this notice is
35 * removed it should not be considered functional, much less stable!
36 *
37 * TODO: test whether leveraging a modern glob implementation might be
38 * worthwhile and portable, or unnecessary complexity. For example:
39 * https://github.com/openbsd/src/blob/master/lib/libc/gen/glob.c
40 *
41 * @brief Routines and structures for getting a list of entities that
42 * match a given pattern.
43 *
44 */
45/** @{ */
46/** @file bu/glob.h */
47
48
49/**
50 * representation of a path element, for use with bu_glob() callbacks.
51 */
52struct bu_dirent {
53 struct bu_vls *name;
54 void *data;
55};
56
57/**
58 * information about a path element (file, directory, object, etc),
59 * for use with bu_glob() callbacks.
60 */
61struct bu_stat {
62 struct bu_vls name;
64 void *data;
65};
66
67
68/**
69 * main structure used by bu_glob() to specify behavior, callbacks,
70 * and return results.
71 */
72struct bu_glob_context {
74#define BU_GLOB_APPEND 0x0001 /**< Append to output from previous call. */
75#define BU_GLOB_NOSORT 0x0020 /**< Don't sort. */
76#define BU_GLOB_NOESCAPE 0x2000 /**< Disable backslash escaping. */
77#define BU_GLOB_ALTDIRFUNC 0x0040 /**< use alternate functions. */
78 int gl_flags; /**< flags customizing globbing behavior */
80 /* Return values */
81
82 int gl_pathc; /**< count of total paths so far */
83 int gl_matchc; /**< count of paths matching pattern */
84 struct bu_vls **gl_pathv; /**< list of paths matching pattern */
86 /* Callback functions */
87
88 struct bu_glob_context *(*gl_opendir)(const char *);
89 int (*gl_readdir)(struct bu_dirent *, struct bu_glob_context *);
92 int (*gl_lstat)(const char *, struct bu_stat *, struct bu_glob_context *);
93 int (*gl_stat)(const char *, struct bu_stat *, struct bu_glob_context *);
95#define BU_GLOB_NOMATCH (-1) /**< No match. */
96#define BU_GLOB_ABORTED (-2) /**< Unignored error. */
97 int (*gl_errfunc)(const char *, int, struct bu_glob_context *);
99 /* For caller use */
100
101 void *data; /**< data passed to all callbacks */
103 /* Private */
104
105 void *priv; /**< For internal use only */
107typedef struct bu_glob_context bu_glob_t;
109
110/**
111 * declaration statement initialization of a bu_glob struct
112 */
113#define BU_GLOB_INIT_ZERO {0, 0, 0, NULL, (struct bu_glob_context *(*)(const char *))NULL, (int(*)(struct bu_dirent *, struct bu_glob_context *))NULL, (void(*)(struct bu_glob_context *))NULL, (int(*)(const char *, struct bu_stat *, struct bu_glob_context *))NULL, (int(*)(const char *, struct bu_stat *, struct bu_glob_context *))NULL, (int(*)(const char *, int, struct bu_glob_context *))NULL, NULL, NULL}
115
116/**
117 * initialize a globbing context for use prior to calling bu_glob()
118 */
121
122/**
123 * release any resources allocated during bu_glob(), including any
124 * returned paths
125 */
126BU_EXPORT extern void bu_glob_free(struct bu_glob_context *);
128
129/**
130 * match a pattern against a set of elements.
131 *
132 * This interface is a somewhat simplified and abstracted version of
133 * UNIX glob matching, based loosely on the interface specified in
134 * POSIX.2. It supports user specified callback functions allowing
135 * callers to glob nearly any named storage structure. By default,
136 * globbing will map to the local filesystem.
137 *
138 * Function takes an input pattern, a set of flags, and a globbing
139 * context from bu_glob_alloc().
140 *
141 * Returns zero on success, non-zero on failure.
142 *
143 * gl_pathc will contain the total number of paths matched. This will
144 * increment previous glob counts if GLOB_APPEND is specified.
145 *
146 * gl_matchc will contain the number of matched paths for this
147 * invocation of bu_glob().
148 *
149 * gl_pathv contains a list of matched paths.
150 */
151BU_EXPORT extern int bu_glob(const char *pattern, int flags, struct bu_glob_context *context);
153/** @} */
154
155
157
158#endif /* BU_GLOB_H */
159
160/*
161 * Local Variables:
162 * mode: C
163 * tab-width: 8
164 * indent-tabs-mode: t
165 * c-file-style: "stroustrup"
166 * End:
167 * ex: shiftwidth=4 tabstop=8
168 */
Definition dvec.h:74
Header file for the BRL-CAD common definitions.
struct bu_glob_context * bu_glob_init(void)
void bu_glob_free(struct bu_glob_context *)
int bu_glob(const char *pattern, int flags, struct bu_glob_context *context)
#define b_off_t
Definition common.h:223
void * data
Definition glob.h:55
struct bu_vls * name
Definition glob.h:54
int(* gl_readdir)(struct bu_dirent *, struct bu_glob_context *)
Definition glob.h:90
void * data
Definition glob.h:102
void * priv
Definition glob.h:106
int(* gl_lstat)(const char *, struct bu_stat *, struct bu_glob_context *)
Definition glob.h:93
struct bu_vls ** gl_pathv
Definition glob.h:85
int(* gl_stat)(const char *, struct bu_stat *, struct bu_glob_context *)
Definition glob.h:94
int gl_flags
Definition glob.h:79
int gl_pathc
Definition glob.h:83
int gl_matchc
Definition glob.h:84
void(* gl_closedir)(struct bu_glob_context *)
Definition glob.h:91
int(* gl_errfunc)(const char *, int, struct bu_glob_context *)
Definition glob.h:98
Definition glob.h:62
struct bu_vls name
Definition glob.h:63
void * data
Definition glob.h:65
b_off_t size
Definition glob.h:64
Definition vls.h:53