1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/os/ossrv/genericopenlibs/openenvcore/include/dirent.dosc Fri Jun 15 03:10:57 2012 +0200
1.3 @@ -0,0 +1,423 @@
1.4 +/** @file ../include/dirent.h
1.5 +@internalComponent
1.6 +*/
1.7 +
1.8 +/** @fn getdirentries(int x, char *ptr, int y, long *lptr)
1.9 +getdirentries(int fd, char *buf, int nbytes, long *basep)
1.10 +@param x
1.11 +@param ptr
1.12 +@param y
1.13 +@param lptr
1.14 +@return If successful, the number of bytes actually transferred is returned.
1.15 +Otherwise, -1 is returned and the global variable errno is set to indicate the error.
1.16 +
1.17 + The getdirentries system call reads directory entries from the directory
1.18 +referenced by the file descriptor x into the buffer pointed to by ptr, in a file system independent format. Up to y of data will be transferred. The y argument must be greater than or equal to the block size associated
1.19 +with the file, see stat. Some file systems may not support these system
1.20 +calls with buffers smaller than this size.
1.21 +
1.22 + The data in the buffer is a series of dirent
1.23 +@code
1.24 +structures each containing the following entries: u_int32_t d_fileno;
1.25 +u_int16_t d_reclen;
1.26 +u_int8_t d_type;
1.27 +u_int8_t d_namlen;
1.28 +char d_name[MAXNAMELEN + 1];/* see below */
1.29 +@endcode
1.30 +
1.31 + The d_fileno entry is a number which is unique for each distinct file in
1.32 + the file system. Files that are linked by hard links (see link ) have the same d_fileno. The d_reclen entry is the length, in bytes, of the directory record. The d_type entry is the type of the file pointed to by the directory record.
1.33 + The file type values are defined in \<sys/dirent.h\>. Presently, however, file type is not supported
1.34 + and d_type is set to 0. The d_name entry contains a null terminated file name. The d_namlen entry specifies the length of the file name excluding the null
1.35 + byte. Thus the actual size of d_name may vary from 1 to MAXNAMELEN + 1.
1.36 +
1.37 + Entries may be separated by extra space.
1.38 +The d_reclen entry may be used as an offset from the start of a dirent structure to the next structure, if any.
1.39 +
1.40 + The actual number of bytes transferred is returned. The current position pointer
1.41 + associated with x is set to point to the next block of entries. The pointer may not
1.42 + advance by the number of bytes returned by getdirentries . A value of zero is returned when the end of the directory
1.43 + has been reached.
1.44 +
1.45 + The getdirentries system call writes the position of the block read into
1.46 + the location pointed to by lptr. Alternatively, the current position pointer may be set and retrieved
1.47 + by lseek. The current position pointer should only
1.48 + be set to a value returned by lseek, a value returned in the location pointed
1.49 + to by basep ( (getdirentries); only) or zero.
1.50 +
1.51 +Examples:
1.52 +@code
1.53 +/* reading directory stream using getdirenttries */
1.54 +/* considering directory c: emp already exists */
1.55 +#include <stdio.h>
1.56 +int main()
1.57 +{
1.58 + int retval;
1.59 + long basep=(off_t) 0;
1.60 + char buf[1024];
1.61 + struct dirent * d;
1.62 + char * dname="C:\ emp\
1.63 + char * fname="C:\ emp\input.txt";
1.64 + int fd,fd1;
1.65 + fd1=open(fname,O_WRONLY|O_CREAT);
1.66 + if(fd==-1)
1.67 + {
1.68 + printf("file creation failed");
1.69 + return -1;
1.70 + }
1.71 + fd=open(dname,O_RDONLY);
1.72 + if(fd==-1)
1.73 + {
1.74 + printf("directory opening failed");
1.75 + return -1;
1.76 + }
1.77 + retval = getdirentries (fd, buf,(unsigned int)sizeof (buf),&basep);
1.78 + if(retval == -1)
1.79 + {
1.80 + printf("getdirentries call failed");
1.81 + return -1;
1.82 + }
1.83 +
1.84 + d=(struct dirent *)buf;
1.85 +
1.86 + printf("name of the file in the newly created directory is \"%s\",d-d_name);
1.87 +
1.88 + close(fd1);
1.89 + close(fd);
1.90 + return 0;
1.91 +}
1.92 +
1.93 +@endcode
1.94 + Output
1.95 +@code
1.96 +name of the file in the newly created directory is "input.txt"
1.97 +
1.98 +@endcode
1.99 +@see lseek()
1.100 +@see open()
1.101 +
1.102 +
1.103 +
1.104 +
1.105 +@publishedAll
1.106 +@externallyDefinedApi
1.107 +*/
1.108 +
1.109 +/** @fn opendir(const char *_path)
1.110 +@param _path
1.111 +
1.112 +Note: This description also covers the following functions -
1.113 + readdir() readdir_r() telldir() seekdir() rewinddir() closedir() dirfd()
1.114 +
1.115 +@return closedir function returns 0 on success or -1 on failure.
1.116 +
1.117 + The opendir function
1.118 +opens the directory named by _path ,
1.119 +associates a directory stream with it
1.120 +and
1.121 +returns a pointer to be used to identify the directory stream in subsequent operations.
1.122 +The pointer NULL is returned if filename cannot be accessed, or if it cannot malloc enough memory to hold the whole thing.
1.123 +
1.124 + The readdir function
1.125 +returns a pointer to the next directory entry.
1.126 +It returns NULL upon reaching the end of the directory or detecting an invalid seekdir operation.
1.127 +
1.128 + The readdir_r function
1.129 +provides the same functionality as readdir ,
1.130 +but the caller must provide a directory entry buffer to store the results in.
1.131 +If the read succeeds, result is pointed at the entry ;
1.132 +upon reaching the end of the directory result is set to NULL .
1.133 +The readdir_r function
1.134 +returns 0 on success or an error number to indicate failure.
1.135 +
1.136 + The telldir function
1.137 +returns the current location associated with the named directory stream .
1.138 +Values returned by telldir are good only for the lifetime of the DIR pointer, dirp ,
1.139 +from which they are derived.
1.140 +If the directory is closed and then
1.141 +reopened, prior values returned by telldir will no longer be valid.
1.142 +
1.143 + The seekdir function
1.144 +sets the position of the next readdir operation on the directory stream .
1.145 +The new position reverts to the one associated with the directory stream when the telldir operation was performed.
1.146 +
1.147 + The rewinddir function
1.148 +resets the position of the named directory stream to the beginning of the directory.
1.149 +
1.150 + The closedir function
1.151 +closes the named directory stream and frees the structure associated with the dirp pointer,
1.152 +returning 0 on success.
1.153 +On failure, -1 is returned and the global variable errno is set to indicate the error.
1.154 +
1.155 + The dirfd function
1.156 +returns the integer file descriptor associated with the named directory stream ,
1.157 +see open .
1.158 +
1.159 +@code
1.160 + Sample code which searches a directory for entry ‘‘name’’ is: len = strlen(name);
1.161 +dirp = opendir(".");
1.162 +while ((dp = readdir(dirp)) != NULL)
1.163 + if (dp->d_namlen == len && !strcmp(dp->d_name, name)) {
1.164 + (void)closedir(dirp);
1.165 + return FOUND;
1.166 + }
1.167 +(void)closedir(dirp);
1.168 +return NOT_FOUND;
1.169 +@endcode
1.170 +
1.171 +Examples:
1.172 +@code
1.173 +/* Detailed description: This test code demonstrates usage of opendir system call, open directory name test.
1.174 + Preconditions: Expects Test directory to be present in the current working directory.
1.175 +*/
1.176 + #include <sys/types.h>
1.177 + #include <dirent.h>
1.178 +int main()
1.179 +{
1.180 + DIR *DirHandle;
1.181 + if(!(DirHandle = opendir("Test") ) )
1.182 + {
1.183 + printf("Failed to open directory Test\n");
1.184 + return -1;
1.185 + }
1.186 + printf("Directory Test opened \n");
1.187 + return 0;
1.188 +}
1.189 +@endcode
1.190 +@code
1.191 +Output
1.192 +Directory Test opened
1.193 +@endcode
1.194 +
1.195 +Limitations:
1.196 +
1.197 +The filename parameter of the opendir() function should not exceed 256 characters in length.
1.198 +
1.199 +@see close()
1.200 +@see lseek()
1.201 +@see open()
1.202 +@see read()
1.203 +
1.204 +
1.205 +
1.206 +
1.207 +@publishedAll
1.208 +@externallyDefinedApi
1.209 +*/
1.210 +
1.211 +/** @fn readdir(DIR *dp)
1.212 +@param dp
1.213 +Refer to opendir() for the documentation
1.214 +@see close()
1.215 +@see lseek()
1.216 +@see open()
1.217 +@see read()
1.218 +
1.219 +
1.220 +
1.221 +
1.222 +@publishedAll
1.223 +@externallyDefinedApi
1.224 +*/
1.225 +
1.226 +
1.227 +/** @fn rewinddir(DIR *dp)
1.228 +@param dp
1.229 +Refer to opendir() for the documentation
1.230 +@see close()
1.231 +@see lseek()
1.232 +@see open()
1.233 +@see read()
1.234 +
1.235 +
1.236 +
1.237 +
1.238 +@publishedAll
1.239 +@externallyDefinedApi
1.240 +*/
1.241 +
1.242 +/** @fn alphasort(const void *d1, const void *d2)
1.243 +@param d1
1.244 +@param d2
1.245 +Refer to scandir() for the documentation
1.246 +@see directory()
1.247 +@see malloc()
1.248 +@see qsort()
1.249 +@see dir()
1.250 +
1.251 +
1.252 +
1.253 +
1.254 +@publishedAll
1.255 +@externallyDefinedApi
1.256 +*/
1.257 +
1.258 +/** @fn scandir(const char *dirname, struct dirent ***namelist, int(*)(struct dirent *), int(*)(const void *, const void *))
1.259 +@param dirname
1.260 +@param namelist
1.261 +
1.262 +Note: This description also covers the following functions -
1.263 + alphasort()
1.264 +
1.265 + The scandir function
1.266 +reads the directory dirname and builds an array of pointers to directory
1.267 +entries using malloc It returns the number of entries in the array.
1.268 +A pointer to the array of directory entries is stored in the location
1.269 +referenced by namelist.
1.270 +
1.271 + The select argument is a pointer to a user supplied subroutine which is called by scandir to select which entries are to be included in the array.
1.272 +The select routine is passed a
1.273 +pointer to a directory entry and should return a non-zero
1.274 +value if the directory entry is to be included in the array.
1.275 +If select is null, then all the directory entries will be included.
1.276 +
1.277 + The compar argument is a pointer to a user supplied subroutine which is passed to qsort to sort the completed array.
1.278 +If this pointer is null, the array is not sorted.
1.279 +
1.280 + The alphasort function
1.281 +is a routine which can be used for the compar argument to sort the array alphabetically.
1.282 +
1.283 + The memory allocated for the array can be deallocated with free ,
1.284 +by freeing each pointer in the array and then the array itself.
1.285 +
1.286 +Examples:
1.287 +@code
1.288 +//Illustrates how to use scandir API.
1.289 +#include <dirent.h>
1.290 +Void scandirTest()
1.291 + {
1.292 + struct dirent **namelist;
1.293 + int n;
1.294 + // Function call to get the dir entries into the namelist.
1.295 + n = scandir("\home\manjus\GETTEXT", &namelist;, 0, 0);
1.296 +
1.297 + if(n > 0) // if scandir is successful it retuns the number of entries greater than 0
1.298 + {
1.299 + // print all the entries in the directory.
1.300 + while(n--)
1.301 + {
1.302 + printf("dir name @ pos %d is %s",n,namelist[n]->d_name);
1.303 + }
1.304 + }
1.305 + }
1.306 +
1.307 +@endcode
1.308 +Diagnostics:
1.309 + Returns -1 if the directory cannot be opened for reading or if malloc cannot allocate enough memory to hold all the data structures.
1.310 +
1.311 +Limitations:
1.312 +
1.313 +The dirname parameter in scandir() should not exceed 256 characters in length.
1.314 +
1.315 +@see directory()
1.316 +@see malloc()
1.317 +@see qsort()
1.318 +@see dir()
1.319 +
1.320 +
1.321 +
1.322 +
1.323 +@publishedAll
1.324 +@externallyDefinedApi
1.325 +*/
1.326 +
1.327 +/** @fn seekdir(DIR *dp, long index)
1.328 +@param dp
1.329 +@param index
1.330 +Refer to opendir() for the documentation
1.331 +@see close()
1.332 +@see lseek()
1.333 +@see open()
1.334 +@see read()
1.335 +
1.336 +
1.337 +
1.338 +
1.339 +@publishedAll
1.340 +@externallyDefinedApi
1.341 +*/
1.342 +
1.343 +/** @fn telldir(DIR *dp)
1.344 +@param dp
1.345 +Refer to opendir() for the documentation
1.346 +@see close()
1.347 +@see lseek()
1.348 +@see open()
1.349 +@see read()
1.350 +
1.351 +
1.352 +
1.353 +
1.354 +@publishedAll
1.355 +@externallyDefinedApi
1.356 +*/
1.357 +
1.358 +
1.359 +/** @fn closedir(DIR *dp)
1.360 +@param dp
1.361 +Refer to opendir() for the documentation
1.362 +@see close()
1.363 +@see lseek()
1.364 +@see open()
1.365 +@see read()
1.366 +
1.367 +
1.368 +
1.369 +
1.370 +@publishedAll
1.371 +@externallyDefinedApi
1.372 +*/
1.373 +
1.374 +/** @typedef typedef struct _dirdesc DIR
1.375 +
1.376 +defines DIR data type through typedef. A type representing a directory stream.
1.377 +
1.378 +@publishedAll
1.379 +@externallyDefinedApi
1.380 +*/
1.381 +
1.382 +
1.383 +/** @def dirfd(dirp)
1.384 +
1.385 +get directory stream file descriptor
1.386 +
1.387 +@publishedAll
1.388 +@released
1.389 +*/
1.390 +
1.391 +/** @def DTF_HIDEW
1.392 +
1.393 +flags for opendir2. hide whiteout entries.
1.394 +
1.395 +@publishedAll
1.396 +@released
1.397 +*/
1.398 +
1.399 +
1.400 +/** @def DTF_NODUP
1.401 +
1.402 +flags for opendir2. don't return duplicate names.
1.403 +
1.404 +@publishedAll
1.405 +@released
1.406 +*/
1.407 +
1.408 +
1.409 +/** @def DTF_REWIND
1.410 +
1.411 +flags for opendir2. rewind after reading union stack.
1.412 +
1.413 +@publishedAll
1.414 +@released
1.415 +*/
1.416 +
1.417 +
1.418 +/** @def __DTF_READALL
1.419 +
1.420 +flags for opendir2. everything has been read.
1.421 +
1.422 +@publishedAll
1.423 +@released
1.424 +*/
1.425 +
1.426 +