Return to glob.3 CVS log

Up to [CSRG BSD Unix] / 43BSDReno / lib / libc / gen

Annotation of 43BSDReno/lib/libc/gen/glob.3, revision 1.1

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.