4.4BSD/usr/share/man/cat3/rewinddir.0

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

NNAAMMEE
     ooppeennddiirr, rreeaaddddiirr, tteellllddiirr, sseeeekkddiirr, rreewwiinnddddiirr, cclloosseeddiirr, ddiirrffdd - directo-
     ry operations

SSYYNNOOPPSSIISS
     ##iinncclluuddee <<ssyyss//ttyyppeess..hh>>
     ##iinncclluuddee <<ddiirreenntt..hh>>

     _D_I_R _*
     ooppeennddiirr(_c_o_n_s_t _c_h_a_r _*_f_i_l_e_n_a_m_e);

     _s_t_r_u_c_t _d_i_r_e_n_t _*
     rreeaaddddiirr(_D_I_R _*_d_i_r_p);

     _l_o_n_g
     tteellllddiirr(_c_o_n_s_t _D_I_R _*_d_i_r_p);

     _v_o_i_d
     sseeeekkddiirr(_D_I_R _*_d_i_r_p, _l_o_n_g _l_o_c);

     _v_o_i_d
     rreewwiinnddddiirr(_D_I_R _*_d_i_r_p);

     _i_n_t
     cclloosseeddiirr(_D_I_R _*_d_i_r_p);

     _i_n_t
     ddiirrffdd(_D_I_R _*_d_i_r_p);

DDEESSCCRRIIPPTTIIOONN
     The ooppeennddiirr() function opens the directory named by _f_i_l_e_n_a_m_e, associates
     a _d_i_r_e_c_t_o_r_y _s_t_r_e_a_m with it and returns a pointer to be used to identify
     the _d_i_r_e_c_t_o_r_y _s_t_r_e_a_m in subsequent operations.  The pointer NULL is re-
     turned if _f_i_l_e_n_a_m_e cannot be accessed, or if it cannot malloc(3) enough
     memory to hold the whole thing.

     The rreeaaddddiirr() function returns a pointer to the next directory entry.  It
     returns NULL upon reaching the end of the directory or detecting an in-
     valid sseeeekkddiirr() operation.

     The tteellllddiirr() function returns the current location associated with the
     named _d_i_r_e_c_t_o_r_y _s_t_r_e_a_m.

     The sseeeekkddiirr() function sets the position of the next rreeaaddddiirr() operation
     on the _d_i_r_e_c_t_o_r_y _s_t_r_e_a_m. The new position reverts to the one associated
     with the _d_i_r_e_c_t_o_r_y _s_t_r_e_a_m when the tteellllddiirr() operation was performed.
     Values returned by tteellllddiirr() are good only for the lifetime of the DIR
     pointer, _d_i_r_p, from which they are derived.  If the directory is closed
     and then reopened, the tteellllddiirr() value may be invalidated due to unde-
     tected directory compaction.  It is safe to use a previous tteellllddiirr() val-
     ue immediately after a call to ooppeennddiirr() and before any calls to
     rreeaaddddiirr().

     The rreewwiinnddddiirr() function resets the position of the named _d_i_r_e_c_t_o_r_y
     _s_t_r_e_a_m to the beginning of the directory.

     The cclloosseeddiirr() function closes the named _d_i_r_e_c_t_o_r_y _s_t_r_e_a_m and frees the
     structure associated with the _d_i_r_p pointer, returning 0 on success.  On
     failure, -1 is returned and the global variable _e_r_r_n_o is set to indicate
     the error.

     The ddiirrffdd() function returns the integer file descriptor associated with
     the named _d_i_r_e_c_t_o_r_y _s_t_r_e_a_m, 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;

SSEEEE AALLSSOO
     open(2),  close(2),  read(2),  lseek(2),  dir(5)

HHIISSTTOORRYY
     The ooppeennddiirr(), rreeaaddddiirr(), tteellllddiirr(), sseeeekkddiirr(), rreewwiinnddddiirr(), cclloosseeddiirr(),
     and ddiirrffdd() functions appeared in 4.2BSD.

4.2 Berkeley Distribution        June 4, 1993                                2