Permission to use, copy, modify, and distribute this software for any
purpose with or without fee is hereby granted, provided that the above
copyright notice and this permission notice appear in all copies.
THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
$Id: isc_dir.3,v 1.2 2000/07/27 09:42:45 tale Exp $
.Dd Jun 30, 2000 .Dt ISC_DIR 3 .Os BIND9 9 .Sh NAME .Nm isc_dir_init , .Nm isc_dir_open , .Nm isc_dir_read , .Nm isc_dir_close , .Nm isc_dir_reset , .Nm isc_dir_chdir .Nd file system directory operations .Sh SYNOPSIS .Fd #include <config.h> .Fd #include <errno.h> .Fd #include <unistd.h> .Fd #include <isc/dir.h> .Fd #include <isc/magic.h> .Fd #include <isc/string.h> .Fd #include <isc/util.h> .Fd #include \*qerrno2result.h\*q .Ft void .Fo isc_dir_init .Fa "isc_dir_t *dir" .Fc .Ft isc_result_t .Fo isc_dir_open .Fa "isc_dir_t *dir, .Fa "const char *dirname" .Fc .Ft isc_result_t .Fo isc_dir_read .Fa "isc_dir_t *dir" .Fc .Ft isc_result_t .Fo isc_dir_close .Fa "isc_dir_t *dir" .Fc .Ft isc_result_t .Fo isc_dir_chdir .Fa "const char *dirname" .Fc .Sh DESCRIPTION These functions define the operations performed on the file system's directories by the name server. They are intended to isolate BIND9 from the semantics of the underlying directory access routines provided by the operating system, BIND9 uses an internal structure of type .Fa isc_dir_t to reference a directory. The contents of this structure are OS-specific. .Fn isc_dir_init initialises the directory structure pointed at .Fa dir . All functions taking a .Fa dir argument must ensure that this parameter points at a valid .Fa isc_dir_t structure.
p .Fn isc_dir_open opens the directory named by .Fa dirname .
p .Fn isc_dir_read retrieves the next entry from the file descriptor associated with directory .Fa dir . The name of that entry and the length of its name are copied to .Fa dir . A successful initial call to .Fn isc_dir_read on a directory will populate the .Fa isc_dir_t with details of the first valid directory entry. Subsequent calls fetch the next entries.
p The .Fn isc_dir_close function closes the file descriptor associated with .Fa dir .
p .Fn isc_dir_reset repositions .Fa dir to the start of the directory.
p The name server's current directory is changed to .Fa dirname by .Fn isc_dir_chdir .
p .Sh RETURN VALUES Successful calls to .Fn isc_dir_open , .Fn isc_dir_read , .Fn isc_dir_reset , .Fn isc_dir_read and .Fn isc_dir_chdir return .Er ISC_R_SUCCESS . .Fn isc_dir_read returns .Er ISC_R_NOMORE when there are no more entries in the directory. .Er ISC_R_UNEXPECTED is returned if the name of the next directory entry is too big to fit in the .Fa isc_dir_t structure. If .Fn isc_dir_chdir fails, .Er ISC_R_INVALIDFILE is returned if .Fa dirname is not a directory, or .Er ISC_R_NOPERM if access permission is denied or .Er ISC_R_IOERROR if an I/O error occurs. The WinNT version of .Fn isc_dir_chdir returns .Er ISC_R_NOTIMPLEMENTED when the operating system reports an error that cannot be defined by either a return value of .Er ISC_R_NOTFOUND or .Er ISC_R_UNEXPECTED . An error of .Er ISC_R_FAILURE can be returned in the WinNT versions of .Fn isc_dir_open and .Fn isc_dir_reset . .Sh SEE ALSO .Xr opendir 3 , .Xr readdir 3 , .Xr closedir 3 , .Xr rewinddir 3 , .Xr chdir 2