BSD 4_4 development

[unix-history] / usr / share / man / cat3 / telldir.0

DIRECTORY(3)                BSD Programmer's Manual               DIRECTORY(3)

N\bNA\bAM\bME\bE
     o\bop\bpe\ben\bnd\bdi\bir\br, r\bre\bea\bad\bdd\bdi\bir\br, t\bte\bel\bll\bld\bdi\bir\br, s\bse\bee\bek\bkd\bdi\bir\br, r\bre\bew\bwi\bin\bnd\bdd\bdi\bir\br, c\bcl\blo\bos\bse\bed\bdi\bir\br, d\bdi\bir\brf\bfd\bd - directo-
     ry operations

S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS
     #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bty\byp\bpe\bes\bs.\b.h\bh>\b>
     #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<d\bdi\bir\bre\ben\bnt\bt.\b.h\bh>\b>

     _\bD_\bI_\bR _\b*
     o\bop\bpe\ben\bnd\bdi\bir\br(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bf_\bi_\bl_\be_\bn_\ba_\bm_\be);

     _\bs_\bt_\br_\bu_\bc_\bt _\bd_\bi_\br_\be_\bn_\bt _\b*
     r\bre\bea\bad\bdd\bdi\bir\br(_\bD_\bI_\bR _\b*_\bd_\bi_\br_\bp);

     _\bl_\bo_\bn_\bg
     t\bte\bel\bll\bld\bdi\bir\br(_\bc_\bo_\bn_\bs_\bt _\bD_\bI_\bR _\b*_\bd_\bi_\br_\bp);

     _\bv_\bo_\bi_\bd
     s\bse\bee\bek\bkd\bdi\bir\br(_\bD_\bI_\bR _\b*_\bd_\bi_\br_\bp, _\bl_\bo_\bn_\bg _\bl_\bo_\bc);

     _\bv_\bo_\bi_\bd
     r\bre\bew\bwi\bin\bnd\bdd\bdi\bir\br(_\bD_\bI_\bR _\b*_\bd_\bi_\br_\bp);

     _\bi_\bn_\bt
     c\bcl\blo\bos\bse\bed\bdi\bir\br(_\bD_\bI_\bR _\b*_\bd_\bi_\br_\bp);

     _\bi_\bn_\bt
     d\bdi\bir\brf\bfd\bd(_\bD_\bI_\bR _\b*_\bd_\bi_\br_\bp);

D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN
     The o\bop\bpe\ben\bnd\bdi\bir\br() function opens the directory named by _\bf_\bi_\bl_\be_\bn_\ba_\bm_\be, associates
     a _\bd_\bi_\br_\be_\bc_\bt_\bo_\br_\by _\bs_\bt_\br_\be_\ba_\bm with it and returns a pointer to be used to identify
     the _\bd_\bi_\br_\be_\bc_\bt_\bo_\br_\by _\bs_\bt_\br_\be_\ba_\bm in subsequent operations.  The pointer NULL is re-
     turned if _\bf_\bi_\bl_\be_\bn_\ba_\bm_\be cannot be accessed, or if it cannot malloc(3) enough
     memory to hold the whole thing.

     The r\bre\bea\bad\bdd\bdi\bir\br() function returns a pointer to the next directory entry.  It
     returns NULL upon reaching the end of the directory or detecting an in-
     valid s\bse\bee\bek\bkd\bdi\bir\br() operation.

     The t\bte\bel\bll\bld\bdi\bir\br() function returns the current location associated with the
     named _\bd_\bi_\br_\be_\bc_\bt_\bo_\br_\by _\bs_\bt_\br_\be_\ba_\bm.

     The s\bse\bee\bek\bkd\bdi\bir\br() function sets the position of the next r\bre\bea\bad\bdd\bdi\bir\br() operation
     on the _\bd_\bi_\br_\be_\bc_\bt_\bo_\br_\by _\bs_\bt_\br_\be_\ba_\bm. The new position reverts to the one associated
     with the _\bd_\bi_\br_\be_\bc_\bt_\bo_\br_\by _\bs_\bt_\br_\be_\ba_\bm when the t\bte\bel\bll\bld\bdi\bir\br() operation was performed.
     Values returned by t\bte\bel\bll\bld\bdi\bir\br() are good only for the lifetime of the DIR
     pointer, _\bd_\bi_\br_\bp, from which they are derived.  If the directory is closed
     and then reopened, the t\bte\bel\bll\bld\bdi\bir\br() value may be invalidated due to unde-
     tected directory compaction.  It is safe to use a previous t\bte\bel\bll\bld\bdi\bir\br() val-
     ue immediately after a call to o\bop\bpe\ben\bnd\bdi\bir\br() and before any calls to
     r\bre\bea\bad\bdd\bdi\bir\br().

     The r\bre\bew\bwi\bin\bnd\bdd\bdi\bir\br() function resets the position of the named _\bd_\bi_\br_\be_\bc_\bt_\bo_\br_\by
     _\bs_\bt_\br_\be_\ba_\bm to the beginning of the directory.

     The c\bcl\blo\bos\bse\bed\bdi\bir\br() function closes the named _\bd_\bi_\br_\be_\bc_\bt_\bo_\br_\by _\bs_\bt_\br_\be_\ba_\bm and frees the
     structure associated with the _\bd_\bi_\br_\bp pointer, returning 0 on success.  On
     failure, -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate
     the error.

     The d\bdi\bir\brf\bfd\bd() function returns the integer file descriptor associated with
     the named _\bd_\bi_\br_\be_\bc_\bt_\bo_\br_\by _\bs_\bt_\br_\be_\ba_\bm, see open(2).

     Sample code which searchs a directory for entry ``name'' is:

           len = strlen(name);
           dirp = opendir(".");
           while ((dp = readdir(dirp)) != NULL)
                   if (dp->d_namlen == len && !strcmp(dp->d_name, name)) {
                           (void)closedir(dirp);
                           return FOUND;
                   }
           (void)closedir(dirp);
           return NOT_FOUND;

S\bSE\bEE\bE A\bAL\bLS\bSO\bO
     open(2),  close(2),  read(2),  lseek(2),  dir(5)

H\bHI\bIS\bST\bTO\bOR\bRY\bY
     The o\bop\bpe\ben\bnd\bdi\bir\br(), r\bre\bea\bad\bdd\bdi\bir\br(), t\bte\bel\bll\bld\bdi\bir\br(), s\bse\bee\bek\bkd\bdi\bir\br(), r\bre\bew\bwi\bin\bnd\bdd\bdi\bir\br(), c\bcl\blo\bos\bse\bed\bdi\bir\br(),
     and d\bdi\bir\brf\bfd\bd() functions appeared in 4.2BSD.

4.2 Berkeley Distribution        June 4, 1993                                2