1DIRECTORY(3) 386BSD Programmer's Manual DIRECTORY(3) 2 3NNAAMMEE 4 ooppeennddiirr, rreeaaddddiirr, tteellllddiirr, sseeeekkddiirr, rreewwiinnddddiirr, cclloosseeddiirr, ddiirrffdd - 5 directory operations 6 7SSYYNNOOPPSSIISS 8 ##iinncclluuddee <<ssyyss//ttyyppeess..hh>> 9 ##iinncclluuddee <<ddiirreenntt..hh>> 10 11 _D_I_R * 12 ooppeennddiirr(_c_o_n_s_t _c_h_a_r *_f_i_l_e_n_a_m_e) 13 14 _s_t_r_u_c_t _d_i_r_e_c_t 15 rreeaaddddiirr(_D_I_R *_d_i_r_p) 16 17 _l_o_n_g 18 tteellllddiirr(_c_o_n_s_t _D_I_R *_d_i_r_p) 19 20 _v_o_i_d 21 sseeeekkddiirr(_D_I_R *_d_i_r_p, _l_o_n_g _l_o_c) 22 23 _v_o_i_d 24 rreewwiinnddddiirr(_D_I_R *_d_i_r_p) 25 26 _i_n_t 27 cclloosseeddiirr(_D_I_R *_d_i_r_p) 28 29 _i_n_t 30 ddiirrffdd(_D_I_R *_d_i_r_p) 31 32DDEESSCCRRIIPPTTIIOONN 33 The ooppeennddiirr() function opens the directory named by _f_i_l_e_n_a_m_e, associates 34 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 35 the _d_i_r_e_c_t_o_r_y _s_t_r_e_a_m in subsequent operations. The pointer NULL is 36 returned if _f_i_l_e_n_a_m_e cannot be accessed, or if it cannot malloc(3) enough 37 memory to hold the whole thing. 38 39 The rreeaaddddiirr() function returns a pointer to the next directory entry. It 40 returns NULL upon reaching the end of the directory or detecting an 41 invalid sseeeekkddiirr() operation. 42 43 The tteellllddiirr() function returns the current location associated with the 44 named _d_i_r_e_c_t_o_r_y _s_t_r_e_a_m. 45 46 The sseeeekkddiirr() function sets the position of the next rreeaaddddiirr() operation 47 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 48 with the _d_i_r_e_c_t_o_r_y _s_t_r_e_a_m when the tteellllddiirr() operation was performed. 49 Values returned by tteellllddiirr() are good only for the lifetime of the DIR 50 pointer, _d_i_r_p, from which they are derived. If the directory is closed 51 and then reopened, the tteellllddiirr() value may be invalidated due to 52 undetected directory compaction. It is safe to use a previous tteellllddiirr() 53 value immediately after a call to ooppeennddiirr() and before any calls to 54 rreeaaddddiirr(). 55 56 The rreewwiinnddddiirr() function resets the position of the named _d_i_r_e_c_t_o_r_y 57 _s_t_r_e_a_m to the beginning of the directory. 58 59 The cclloosseeddiirr() function closes the named _d_i_r_e_c_t_o_r_y _s_t_r_e_a_m and frees the 60 structure associated with the _d_i_r_p pointer, returning 0 on success. On 61 failure, -1 is returned and the global variable _e_r_r_n_o is set to indicate 62 the error. 63 64 The ddiirrffdd() function returns the integer file descriptor associated with 65 the named _d_i_r_e_c_t_o_r_y _s_t_r_e_a_m, see open(2). 66 67 Sample code which searchs a directory for entry ``name'' is: 68 69 len = strlen(name); 70 dirp = opendir("."); 71 for (dp = readdir(dirp); dp != NULL; dp = readdir(dirp)) 72 if (dp->d_namlen == len && !strcmp(dp->d_name, name)) { 73 (void)closedir(dirp); 74 return FOUND; 75 } 76 (void)closedir(dirp); 77 return NOT_FOUND; 78 79SSEEEE AALLSSOO 80 open(2), close(2), read(2), lseek(2), dir(5) 81 82HHIISSTTOORRYY 83 The ooppeennddiirr(), rreeaaddddiirr(), tteellllddiirr(), sseeeekkddiirr(), rreewwiinnddddiirr(), cclloosseeddiirr(), 84 and ddiirrffdd() functions appeared in 4.2BSD. 85 864.2 Berkeley Distribution April 19, 1991 2 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133