/contrib/tcsh/glob.3

https://bitbucket.org/freebsd/freebsd-head/ · Unknown · 482 lines · 481 code · 1 blank · 0 comment · 0 complexity · 0d5beb3d7cf33d342fbb6f50360f9ee4 MD5 · raw file

  1. .\" $NetBSD: glob.3,v 1.17 2001/03/16 21:09:05 christos Exp $
  2. .\"
  3. .\" Copyright (c) 1989, 1991, 1993, 1994
  4. .\" The Regents of the University of California. All rights reserved.
  5. .\"
  6. .\" This code is derived from software contributed to Berkeley by
  7. .\" Guido van Rossum.
  8. .\" Redistribution and use in source and binary forms, with or without
  9. .\" modification, are permitted provided that the following conditions
  10. .\" are met:
  11. .\" 1. Redistributions of source code must retain the above copyright
  12. .\" notice, this list of conditions and the following disclaimer.
  13. .\" 2. Redistributions in binary form must reproduce the above copyright
  14. .\" notice, this list of conditions and the following disclaimer in the
  15. .\" documentation and/or other materials provided with the distribution.
  16. .\" 3. Neither the name of the University nor the names of its contributors
  17. .\" may be used to endorse or promote products derived from this software
  18. .\" without specific prior written permission.
  19. .\"
  20. .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  21. .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22. .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23. .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  24. .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25. .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26. .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27. .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28. .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29. .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30. .\" SUCH DAMAGE.
  31. .\"
  32. .\" @(#)glob.3 8.3 (Berkeley) 4/16/94
  33. .\"
  34. .Dd March 31, 1998
  35. .Dt GLOB 3
  36. .Os
  37. .Sh NAME
  38. .Nm glob ,
  39. .Nm globfree
  40. .Nd generate pathnames matching a pattern
  41. .Sh LIBRARY
  42. .Lb libc
  43. .Sh SYNOPSIS
  44. .Fd #include <glob.h>
  45. .Ft int
  46. .Fn glob "const char *pattern" "int flags" "const int (*errfunc)(const char *, int)" "glob_t *pglob"
  47. .Ft void
  48. .Fn globfree "glob_t *pglob"
  49. .Sh DESCRIPTION
  50. The
  51. .Fn glob
  52. function
  53. is a pathname generator that implements the rules for file name pattern
  54. matching used by the shell.
  55. .Pp
  56. The include file
  57. .Pa glob.h
  58. defines the structure type
  59. .Fa glob_t ,
  60. which contains at least the following fields:
  61. .Bd -literal
  62. typedef struct {
  63. int gl_pathc; /* count of total paths so far */
  64. int gl_matchc; /* count of paths matching pattern */
  65. int gl_offs; /* reserved at beginning of gl_pathv */
  66. int gl_flags; /* returned flags */
  67. char **gl_pathv; /* list of paths matching pattern */
  68. } glob_t;
  69. .Ed
  70. .Pp
  71. The argument
  72. .Fa pattern
  73. is a pointer to a pathname pattern to be expanded.
  74. The
  75. .Fn glob
  76. argument
  77. matches all accessible pathnames against the pattern and creates
  78. a list of the pathnames that match.
  79. In order to have access to a pathname,
  80. .Fn glob
  81. requires search permission on every component of a path except the last
  82. and read permission on each directory of any filename component of
  83. .Fa pattern
  84. that contains any of the special characters
  85. .Ql * ,
  86. .Ql ?
  87. or
  88. .Ql [ .
  89. .Pp
  90. The
  91. .Fn glob
  92. argument
  93. stores the number of matched pathnames into the
  94. .Fa gl_pathc
  95. field, and a pointer to a list of pointers to pathnames into the
  96. .Fa gl_pathv
  97. field.
  98. The first pointer after the last pathname is
  99. .Dv NULL .
  100. If the pattern does not match any pathnames, the returned number of
  101. matched paths is set to zero.
  102. .Pp
  103. It is the caller's responsibility to create the structure pointed to by
  104. .Fa pglob .
  105. The
  106. .Fn glob
  107. function allocates other space as needed, including the memory pointed
  108. to by
  109. .Fa gl_pathv .
  110. .Pp
  111. The argument
  112. .Fa flags
  113. is used to modify the behavior of
  114. .Fn glob .
  115. The value of
  116. .Fa flags
  117. is the bitwise inclusive
  118. .Tn OR
  119. of any of the following
  120. values defined in
  121. .Pa glob.h :
  122. .Bl -tag -width GLOB_ALTDIRFUNC
  123. .It Dv GLOB_APPEND
  124. Append pathnames generated to the ones from a previous call (or calls)
  125. to
  126. .Fn glob .
  127. The value of
  128. .Fa gl_pathc
  129. will be the total matches found by this call and the previous call(s).
  130. The pathnames are appended to, not merged with the pathnames returned by
  131. the previous call(s).
  132. Between calls, the caller must not change the setting of the
  133. .Dv GLOB_DOOFFS
  134. flag, nor change the value of
  135. .Fa gl_offs
  136. when
  137. .Dv GLOB_DOOFFS
  138. is set, nor (obviously) call
  139. .Fn globfree
  140. for
  141. .Fa pglob .
  142. .It Dv GLOB_DOOFFS
  143. Make use of the
  144. .Fa gl_offs
  145. field.
  146. If this flag is set,
  147. .Fa gl_offs
  148. is used to specify how many
  149. .Dv NULL
  150. pointers to prepend to the beginning
  151. of the
  152. .Fa gl_pathv
  153. field.
  154. In other words,
  155. .Fa gl_pathv
  156. will point to
  157. .Fa gl_offs
  158. .Dv NULL
  159. pointers,
  160. followed by
  161. .Fa gl_pathc
  162. pathname pointers, followed by a
  163. .Dv NULL
  164. pointer.
  165. .It Dv GLOB_ERR
  166. Causes
  167. .Fn glob
  168. to return when it encounters a directory that it cannot open or read.
  169. Ordinarily,
  170. .Fn glob
  171. continues to find matches.
  172. .It Dv GLOB_MARK
  173. Each pathname that is a directory that matches
  174. .Fa pattern
  175. has a slash
  176. appended.
  177. .It Dv GLOB_NOCHECK
  178. If
  179. .Fa pattern
  180. does not match any pathname, then
  181. .Fn glob
  182. returns a list
  183. consisting of only
  184. .Fa pattern ,
  185. with the number of total pathnames is set to 1, and the number of matched
  186. pathnames set to 0.
  187. .It Dv GLOB_NOSORT
  188. By default, the pathnames are sorted in ascending
  189. .Tn ASCII
  190. order;
  191. this flag prevents that sorting (speeding up
  192. .Fn glob ) .
  193. .El
  194. .Pp
  195. The following values may also be included in
  196. .Fa flags ,
  197. however, they are non-standard extensions to
  198. .St -p1003.2 .
  199. .Bl -tag -width GLOB_ALTDIRFUNC
  200. .It Dv GLOB_ALTDIRFUNC
  201. The following additional fields in the pglob structure have been
  202. initialized with alternate functions for glob to use to open, read,
  203. and close directories and to get stat information on names found
  204. in those directories.
  205. .Bd -literal
  206. void *(*gl_opendir)(const char * name);
  207. struct dirent *(*gl_readdir)(void *);
  208. void (*gl_closedir)(void *);
  209. int (*gl_lstat)(const char *name, struct stat *st);
  210. int (*gl_stat)(const char *name, struct stat *st);
  211. .Ed
  212. .Pp
  213. This extension is provided to allow programs such as
  214. .Xr restore 8
  215. to provide globbing from directories stored on tape.
  216. .It Dv GLOB_BRACE
  217. Pre-process the pattern string to expand
  218. .Ql {pat,pat,...}
  219. strings like
  220. .Xr csh 1 .
  221. The pattern
  222. .Ql {}
  223. is left unexpanded for historical reasons
  224. .Po
  225. .Xr csh 1
  226. does the same thing to ease typing of
  227. .Xr find 1
  228. patterns
  229. .Pc .
  230. .It Dv GLOB_MAGCHAR
  231. Set by the
  232. .Fn glob
  233. function if the pattern included globbing characters.
  234. See the description of the usage of the
  235. .Fa gl_matchc
  236. structure member for more details.
  237. .It Dv GLOB_NOMAGIC
  238. Is the same as
  239. .Dv GLOB_NOCHECK
  240. but it only appends the
  241. .Fa pattern
  242. if it does not contain any of the special characters ``*'', ``?'' or ``[''.
  243. .Dv GLOB_NOMAGIC
  244. is provided to simplify implementing the historic
  245. .Xr csh 1
  246. globbing behavior and should probably not be used anywhere else.
  247. .It Dv GLOB_NOESCAPE
  248. Disable the use of the backslash
  249. .Pq Ql \e
  250. character for quoting.
  251. .It Dv GLOB_TILDE
  252. Expand patterns that start with
  253. .Ql ~
  254. to user name home directories.
  255. .It Dv GLOB_LIMIT
  256. Limit the amount of memory used by matches to
  257. .Li ARG_MAX
  258. This option should be set for programs that can be coerced to a denial of
  259. service attack via patterns that expand to a very large number of matches,
  260. such as a long string of
  261. .Li */../*/..
  262. .El
  263. .Pp
  264. If, during the search, a directory is encountered that cannot be opened
  265. or read and
  266. .Fa errfunc
  267. is
  268. .Pf non- Dv NULL ,
  269. .Fn glob
  270. calls
  271. .Fa (*errfunc)(path, errno) .
  272. This may be unintuitive: a pattern like
  273. .Ql */Makefile
  274. will try to
  275. .Xr stat 2
  276. .Ql foo/Makefile
  277. even if
  278. .Ql foo
  279. is not a directory, resulting in a
  280. call to
  281. .Fa errfunc .
  282. The error routine can suppress this action by testing for
  283. .Dv ENOENT
  284. and
  285. .Dv ENOTDIR ;
  286. however, the
  287. .Dv GLOB_ERR
  288. flag will still cause an immediate
  289. return when this happens.
  290. .Pp
  291. If
  292. .Fa errfunc
  293. returns non-zero,
  294. .Fn glob
  295. stops the scan and returns
  296. .Dv GLOB_ABORTED
  297. after setting
  298. .Fa gl_pathc
  299. and
  300. .Fa gl_pathv
  301. to reflect any paths already matched.
  302. This also happens if an error is encountered and
  303. .Dv GLOB_ERR
  304. is set in
  305. .Fa flags ,
  306. regardless of the return value of
  307. .Fa errfunc ,
  308. if called.
  309. If
  310. .Dv GLOB_ERR
  311. is not set and either
  312. .Fa errfunc
  313. is
  314. .Dv NULL
  315. or
  316. .Fa errfunc
  317. returns zero, the error is ignored.
  318. .Pp
  319. The
  320. .Fn globfree
  321. function frees any space associated with
  322. .Fa pglob
  323. from a previous call(s) to
  324. .Fn glob .
  325. .Pp
  326. The historical
  327. .Dv GLOB_QUOTE
  328. flag is no longer supported.
  329. Per
  330. .St -p1003.2-92 ,
  331. backslash escaping of special characters is the default behaviour;
  332. it may be disabled by specifying the
  333. .Dv GLOB_NOESCAPE
  334. flag.
  335. .Sh RETURN VALUES
  336. On successful completion,
  337. .Fn glob
  338. returns zero.
  339. In addition the fields of
  340. .Fa pglob
  341. contain the values described below:
  342. .Bl -tag -width GLOB_NOCHECK
  343. .It Fa gl_pathc
  344. contains the total number of matched pathnames so far.
  345. This includes other matches from previous invocations of
  346. .Fn glob
  347. if
  348. .Dv GLOB_APPEND
  349. was specified.
  350. .It Fa gl_matchc
  351. contains the number of matched pathnames in the current invocation of
  352. .Fn glob .
  353. .It Fa gl_flags
  354. contains a copy of the
  355. .Fa flags
  356. parameter with the bit
  357. .Dv GLOB_MAGCHAR
  358. set if
  359. .Fa pattern
  360. contained any of the special characters ``*'', ``?'' or ``['', cleared
  361. if not.
  362. .It Fa gl_pathv
  363. contains a pointer to a
  364. .Dv NULL Ns -terminated
  365. list of matched pathnames.
  366. However, if
  367. .Fa gl_pathc
  368. is zero, the contents of
  369. .Fa gl_pathv
  370. are undefined.
  371. .El
  372. .Pp
  373. If
  374. .Fn glob
  375. terminates due to an error, it sets
  376. .Va errno
  377. and returns one of the following non-zero constants, which are defined
  378. in the include file
  379. .Aq Pa glob.h :
  380. .Bl -tag -width GLOB_ABORTEDXXX
  381. .It Dv GLOB_ABORTED
  382. The scan was stopped because an error was encountered and either
  383. .Dv GLOB_ERR
  384. was set or
  385. .Fa (*errfunc)()
  386. returned non-zero.
  387. .It Dv GLOB_NOMATCH
  388. The pattern does not match any existing pathname, and
  389. .Dv GLOB_NOCHECK
  390. was not set int
  391. .Dv flags .
  392. .It Dv GLOB_NOSPACE
  393. An attempt to allocate memory failed, or if
  394. .Va errno
  395. was 0
  396. .Li GLOB_LIMIT
  397. was specified in the flags and
  398. .Li ARG_MAX
  399. patterns were matched.
  400. .El
  401. .Pp
  402. The historical
  403. .Dv GLOB_ABEND
  404. return constant is no longer supported. Portable applications should use the
  405. .Dv GLOB_ABORTED
  406. constant instead.
  407. .Pp
  408. The arguments
  409. .Fa pglob\->gl_pathc
  410. and
  411. .Fa pglob\->gl_pathv
  412. are still set as specified above.
  413. .Sh ENVIRONMENT
  414. .Bl -tag -width HOME -compact
  415. .It Ev HOME
  416. If defined, used as the home directory of the current user in
  417. tilde expansions.
  418. .El
  419. .Sh EXAMPLE
  420. A rough equivalent of
  421. .Ql "ls -l *.c *.h"
  422. can be obtained with the
  423. following code:
  424. .Bd -literal -offset indent
  425. glob_t g;
  426. g.gl_offs = 2;
  427. glob("*.c", GLOB_DOOFFS, NULL, &g);
  428. glob("*.h", GLOB_DOOFFS | GLOB_APPEND, NULL, &g);
  429. g.gl_pathv[0] = "ls";
  430. g.gl_pathv[1] = "-l";
  431. execvp("ls", g.gl_pathv);
  432. .Ed
  433. .Sh SEE ALSO
  434. .Xr sh 1 ,
  435. .Xr fnmatch 3 ,
  436. .Xr regexp 3
  437. .Sh STANDARDS
  438. The
  439. .Fn glob
  440. function is expected to be
  441. .St -p1003.2
  442. compatible with the exception
  443. that the flags
  444. .Dv GLOB_ALTDIRFUNC,
  445. .Dv GLOB_BRACE
  446. .Dv GLOB_MAGCHAR,
  447. .Dv GLOB_NOMAGIC,
  448. .Dv GLOB_TILDE,
  449. and
  450. .Dv GLOB_LIMIT
  451. and the fields
  452. .Fa gl_matchc
  453. and
  454. .Fa gl_flags
  455. should not be used by applications striving for strict
  456. .Tn POSIX
  457. conformance.
  458. .Sh HISTORY
  459. The
  460. .Fn glob
  461. and
  462. .Fn globfree
  463. functions first appeared in
  464. .Bx 4.4 .
  465. .Sh BUGS
  466. Patterns longer than
  467. .Dv MAXPATHLEN
  468. may cause unchecked errors.
  469. .Pp
  470. The
  471. .Fn glob
  472. function may fail and set
  473. .Va errno
  474. for any of the errors specified for the library routines
  475. .Xr stat 2 ,
  476. .Xr closedir 3 ,
  477. .Xr opendir 3 ,
  478. .Xr readdir 3 ,
  479. .Xr malloc 3 ,
  480. and
  481. .Xr free 3 .