![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to glob.3 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [CSRG BSD Unix] / 43BSDReno / lib / libc / gen|
Return to glob.3 CVS log | Up to [CSRG BSD Unix] / 43BSDReno / lib / libc / gen |
1.1 root 1: .\" Copyright (c) 1989 The Regents of the University of California.
2: .\" All rights reserved.
3: .\"
4: .\" This code is derived from software contributed to Berkeley by
5: .\" Guido van Rossum.
6: .\"
7: .\" Redistribution and use in source and binary forms are permitted provided
8: .\" that: (1) source distributions retain this entire copyright notice and
9: .\" comment, and (2) distributions including binaries display the following
10: .\" acknowledgement: ``This product includes software developed by the
11: .\" University of California, Berkeley and its contributors'' in the
12: .\" documentation or other materials provided with the distribution and in
13: .\" all advertising materials mentioning features or use of this software.
14: .\" Neither the name of the University nor the names of its contributors may
15: .\" be used to endorse or promote products derived from this software without
16: .\" specific prior written permission.
17: .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED
18: .\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
19: .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
20: .\"
21: .\" @(#)glob.3 5.2 (Berkeley) 6/23/90
22: .\"
23: .TH GLOB 3 "June 23, 1990"
24: .UC 7
25: .SH NAME
26: glob, globfree \- generate pathnames matching a pattern
27: .SH SYNOPSIS
28: .nf
29: #include <glob.h>
30:
31: glob(const char *pattern, int flags,
32: const int (*errfunc)(char *, int), glob_t *pglob);
33:
34: void globfree(glob_t *pglob);
35: .fi
36: .SH DESCRIPTION
37: .I Glob
38: is a pathname generator that implements the rules for file name pattern
39: matching used by the shell.
40: .PP
41: The include file
42: .I glob.h
43: defines the structure type
44: .IR glob_t ,
45: which contains at least the following fields:
46: .sp
47: .RS
48: .nf
49: .ta .5i +\w'char **gl_pathv;\0\0\0'u
50: typedef struct {
51: int gl_pathc; /* count of paths matching pattern */
52: int gl_offs; /* reserved at beginning of gl_pathv */
53: char **gl_pathv; /* list of paths matching pattern */
54: } glob_t;
55: .fi
56: .RE
57: .PP
58: The argument
59: .I pattern
60: is a pointer to a pathname pattern to be expanded.
61: .I Glob
62: matches all accessible pathnames against the pattern and creates
63: a list of the pathnames that match.
64: In order to have access to a pathname,
65: .I glob
66: requires search permission on every component of a path except the last
67: and read permission on each directory of any filename component of
68: .I pattern
69: that contains any of the special characters ``*'', ``?'' or ``[''.
70: .PP
71: .I Glob
72: stores the number of matched pathnames into the
73: .I gl_pathc
74: field, and a pointer to a list of pointers to pathnames into the
75: .I gl_pathv
76: field.
77: The first pointer after the last pathname is NULL.
78: If the pattern does not match any pathnames, the returned number of
79: matched paths is set to zero.
80: .PP
81: It is the caller's responsibility to create the structure pointed to by
82: .IR pglob .
83: The
84: .I glob
85: function allocates other space as needed, including the memory pointed
86: to by
87: .IR gl_pathv .
88: .PP
89: The argument
90: .I flags
91: is used to modify the behavior of
92: .IR glob .
93: The value of
94: .I flags
95: is the bitwise inclusive OR of any of the following
96: values defined in
97: .IR glob.h :
98: .TP
99: GLOB_APPEND
100: Append pathnames generated to the ones from a previous call (or calls)
101: to
102: .IR glob .
103: The value of
104: .I gl_pathc
105: will be the total matches found by this call and the previous call(s).
106: The pathnames are appended to, not merged with the pathnames returned by
107: the previous call(s).
108: Between calls, the caller must not change the setting of the
109: GLOB_DOOFFS flag, nor change the value of
110: .I gl_offs
111: when
112: GLOB_DOOFFS is set, nor (obviously) call
113: .I globfree
114: for
115: .I pglob.
116: .TP
117: GLOB_DOOFFS
118: Make use of the
119: .I gl_offs
120: field.
121: If this flag is set,
122: .I gl_offs
123: is used to specify how many NULL pointers to prepend to the beginning
124: of the
125: .I gl_pathv
126: field.
127: In other words,
128: .I gl_pathv
129: will point to
130: .I gl_offs
131: NULL pointers,
132: followed by
133: .I gl_pathc
134: pathname pointers, followed by a NULL pointer.
135: .TP
136: GLOB_ERR
137: Causes
138: .I glob
139: to return when it encounters a directory that it cannot open or read.
140: Ordinarily,
141: .I glob
142: continues to find matches.
143: .TP
144: GLOB_MARK
145: Each pathname that is a directory that matches
146: .I pattern
147: has a slash
148: appended.
149: .TP
150: GLOB_NOSORT
151: By default, the pathnames are sorted in ascending ASCII order;
152: this flag prevents that sorting (speeding up
153: .IR glob ).
154: .TP
155: GLOB_NOCHECK
156: If
157: .I pattern
158: does not match any pathname, then
159: .I glob
160: returns a list
161: consisting of only
162: .IR pattern ,
163: and the number of matched pathnames is set to 1.
164: If
165: .I GLOB_QUOTE
166: is set, its effect is present in the pattern returned.
167: .TP
168: GLOB_QUOTE
169: Use the backslash (``\e'') character for quoting: every occurrence of
170: a backslash followed by a character in the pattern is replaced by that
171: character, avoiding any special interpretation of the character.
172: .PP
173: If, during the search, a directory is encountered that cannot be opened
174: or read and
175: .I errfunc
176: is non-NULL,
177: .I glob
178: calls (*\fIerrfunc\fP)(\fIpath\fP, \fIerrno\fP).
179: This may be unintuitive: a pattern like ``*/Makefile'' will try to
180: .IR stat (2)
181: ``foo/Makefile'' even if ``foo'' is not a directory, resulting in a
182: call to
183: .IR errfunc .
184: The error routine can suppress this action by testing for ENOENT and
185: ENOTDIR; however, the GLOB_ERR flag will still cause an immediate
186: return when this happens.
187: .PP
188: If
189: .I errfunc
190: returns non-zero,
191: .I glob
192: stops the scan and returns
193: .I GLOB_ABEND
194: after setting
195: .I gl_pathc
196: and
197: .I gl_pathv
198: to reflect any paths already matched.
199: This also happens if an error is encountered and
200: .I GLOB_ERR
201: is set in
202: .IR flags ,
203: regardless of the return value of
204: .IR errfunc ,
205: if called.
206: If
207: .I GLOB_ERR
208: is not set and either
209: .I errfunc
210: is NULL or
211: .I errfunc
212: returns zero, the error is ignored.
213: .PP
214: The
215: .I globfree
216: function frees any space associated with
217: .I pglob
218: from a previous call(s) to
219: .IR glob .
220: .SH RETURNS
221: On successful completion,
222: .I glob
223: returns zero.
224: The field
225: .I gl_pathc
226: returns the number of matched pathnames and
227: the field
228: .I gl_pathv
229: contains a pointer to a NULL-terminated list of matched pathnames.
230: However, if
231: .I pglob->gl_pathc
232: is zero, the contents of
233: .I pglob->gl_pathv
234: is undefined.
235: .PP
236: If
237: .I glob
238: terminates due to an error, it sets errno and returns one of the
239: following non-zero constants, which are defined in the include
240: file <glob.h>:
241: .TP
242: GLOB_NOSPACE
243: An attempt to allocate memory failed.
244: .TP
245: GLOB_ABEND
246: The scan was stopped because an error was encountered and either
247: GLOB_ERR was set or (*\fIerrfunc\fR)() returned non-zero.
248: .PP
249: The arguments
250: .I pglob->gl_pathc
251: and
252: .I pglob->gl_pathv
253: are still set as specified above.
254: .SH STANDARDS
255: The
256: .I glob
257: function is expected to be POSIX 1003.2 compatible with the exception
258: that the flag GLOB_QUOTE should not be used by applications striving
259: for strict POSIX conformance.
260: .SH EXAMPLE
261: A rough equivalent of ``ls -l *.c *.h'' can be obtained with the
262: following code:
263: .sp
264: .nf
265: .RS
266: glob_t g;
267:
268: g.gl_offs = 2;
269: glob("*.c", GLOB_DOOFFS, NULL, &g);
270: glob("*.h", GLOB_DOOFFS | GLOB_APPEND, NULL, &g);
271: g.gl_pathv[0] = "ls";
272: g.gl_pathv[1] = "-l";
273: execvp("ls", g.gl_pathv);
274: .RE
275: .fi
276: .SH SEE ALSO
277: sh(1), fnmatch(3), wordexp(3), regexp(3)
278: .SH BUGS
279: Patterns longer than MAXPATHLEN may cause unchecked errors.
280: .PP
281: .I Glob
282: may fail and set errno for any of the errors specified for the
283: library routines
284: .I stat (2),
285: .I closedir (3),
286: .I opendir (3),
287: .I readdir (3),
288: .I malloc (3),
289: and
290: .I free (3).
291:
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.