telldir man page on BSDi

Man page or keyword search:  
man Server   6284 pages
apropos Keyword Search (all sections)
Output format
BSDi logo
[printable version]

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

NAME
     opendir, readdir, readdir_r, telldir, seekdir, rewinddir, closedir, dirfd
     - directory operations

SYNOPSIS
     #include <sys/types.h>
     #include <dirent.h>

     DIR *
     opendir(const char *filename);

     struct dirent *
     readdir(DIR *dirp);

     int
     readdir_r(DIR *dirp, struct dirent *buf, struct dirent **retval);

     long
     telldir(const DIR *dirp);

     void
     seekdir(DIR *dirp, long loc);

     void
     rewinddir(DIR *dirp);

     int
     closedir(DIR *dirp);

     int
     dirfd(DIR *dirp);

DESCRIPTION
     The opendir() function opens the directory named by filename, associates
     a directory stream with it and returns a pointer to be used to identify
     the directory stream in subsequent operations.

     The readdir() function returns a pointer to the next directory entry.  A
     directory entry has the form:

     struct dirent {
	     u_int32_t	     d_fileno;
	     u_int16_t	     d_reclen;
	     u_int8_t	     d_type;
	     u_int8_t	     d_namlen;
	     char	     d_name[NAME_MAX + 1];
     };

     The nul-terminated name of the entry is contained in the d_name field.

     The readdir_r() function is a reentrant version of the traditional
     readdir() call.  If it has not reached the end of the directory, it uses
     the supplied pointer buf to hold the return value, and then sets retval
     to point to this structure.  The supplied buffer must have room for at
     least NAME_MAX bytes of file name in its d_name field.  (In BSD/OS, any
     dirent structure has sufficient space automatically.)

     The telldir() function returns the current location associated with the
     named directory stream.

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

     The rewinddir() function resets the position of the named directory
     stream to the beginning of the directory.

     The closedir() function closes the named directory stream and frees the
     structure associated with the dirp pointer.

     The dirfd() macro returns the integer file descriptor associated with the
     named directory stream; see open(2).  You may only call dirfd() on a
     valid directory stream; otherwise, the result is undefined.

     Here is some sample code which searches the current directory for an en-
     try ``name'':

	   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;

RETURN VALUES
     If opendir() succeeds, it returns a pointer to a valid DIR structure.
     Otherwise, it returns NULL and sets the global variable errno to indicate
     the error.

     If readdir() succeeds, it returns a pointer to a valid dirent structure.
     If readdir() reaches the end of the directory, it returns NULL and pre-
     serves the value of errno. Otherwise, it returns NULL and sets errno to
     indicate the error.

     If readdir_r() succeeds, it returns 0.  If readdir_r() reaches the end of
     the directory, it sets *retval to NULL and returns 0.  Otherwise,
     readdir_r() returns an error number to indicate the error.

     If telldir() succeeds, it returns a value that may later be provided to
     seekdir() to restore the current position in the directory; otherwise, it
     returns -1 and sets errno to indicate the error.

     If closedir() succeeds, it returns 0; otherwise, it returns -1 and sets
     errno to indicate the error.

ERRORS
     Opendir() will fail if:

     [EACCES]	   Search permission is denied for a component of the path
		   prefix.

     [EACCES]	   Read permission is denied for the directory.

     [EMFILE]	   The process has already reached its limit for open file de-
		   scriptors (see intro(2) and getrlimit(2)).

     [ENAMETOOLONG]
		   A pathname component was longer than NAME_MAX characters,
		   or the total length of the pathname exceeded PATH_MAX char-

		   acters.

     [ENFILE]	   The system file table is full.

     [ENOENT]	   The given directory does not exist.

     [ENOMEM]	   There was insufficient free memory to allocate the DIR
		   structure or one of its subsidiary buffers.

     [ENOTDIR]	   A component of the path prefix is not a directory.

     Closedir(), readdir() and readdir_r() will fail if:

     [EBADF]	   The dirp argument doesn't refer to an open directory
		   stream.

     Telldir() will fail if:

     [ENOMEM]	   There was insufficient free memory to allocate a record de-
		   scribing the current position in the directory.

SEE ALSO
     open(2),  close(2),  read(2),  lseek(2),  dir(5)

HISTORY
     The opendir(), readdir(), telldir(), seekdir(), rewinddir(), closedir(),
     and dirfd() functions appeared in 4.2BSD.

STANDARDS
     The opendir(), readdir(), readdir_r() rewinddir(), and closedir() func-
     tions conform to IEEE Std1003.1-1996 (``POSIX'').

BUGS
     The opendir(), readdir(), telldir(), seekdir(), rewinddir(), closedir(),
     and dirfd() functions may not be safely called concurrently from multiple
     threads, e.g., the interfaces described by pthreads(3).

4.2 Berkeley Distribution	 June 4, 1993				     3
[top]

List of man pages available for BSDi

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net