Differential D25892 Diff 75344 head/lib/libc/gen/directory.3

Changeset View

Standalone View

head/lib/libc/gen/directory.3

	Show All 22 Lines
	.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT			.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
	.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY			.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
	.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF			.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
	.\" SUCH DAMAGE.			.\" SUCH DAMAGE.
	.\"			.\"
	.\" @(#)directory.3 8.1 (Berkeley) 6/4/93			.\" @(#)directory.3 8.1 (Berkeley) 6/4/93
	.\" $FreeBSD$			.\" $FreeBSD$
	.\"			.\"
	.Dd April 30, 2019			.Dd August 1, 2020
	.Dt DIRECTORY 3			.Dt DIRECTORY 3
	.Os			.Os
	.Sh NAME			.Sh NAME
	.Nm opendir ,			.Nm opendir ,
	.Nm fdopendir ,			.Nm fdopendir ,
	.Nm readdir ,			.Nm readdir ,
	.Nm readdir_r ,			.Nm readdir_r ,
	.Nm telldir ,			.Nm telldir ,
	▲ Show 20 Lines • Show All 197 Lines • ▼ Show 20 Lines
	.Pp			.Pp
	The			The
	.Fn dirfd			.Fn dirfd
	function			function
	returns the integer file descriptor associated with the named			returns the integer file descriptor associated with the named
	.Em directory stream ,			.Em directory stream ,
	see			see
	.Xr open 2 .			.Xr open 2 .
	.Pp			.Sh EXAMPLES
	Sample code which searches a directory for entry ``name'' is:			Sample code which searches a directory for entry ``name'' is:
	.Bd -literal -offset indent			.Bd -literal -offset indent
	dirp = opendir(".");			dirp = opendir(".");
	if (dirp == NULL)			if (dirp == NULL)
	return (ERROR);			return (ERROR);
	len = strlen(name);			len = strlen(name);
	while ((dp = readdir(dirp)) != NULL) {			while ((dp = readdir(dirp)) != NULL) {
	if (dp->d_namlen == len && strcmp(dp->d_name, name) == 0) {			if (dp->d_namlen == len && strcmp(dp->d_name, name) == 0) {
	(void)closedir(dirp);			(void)closedir(dirp);
	return (FOUND);			return (FOUND);
	}			}
	}			}
	(void)closedir(dirp);			(void)closedir(dirp);
	return (NOT_FOUND);			return (NOT_FOUND);
	.Ed			.Ed
				.Sh ERRORS
				The
				.Fn opendir
				function will fail if:
				.Bl -tag -width Er
				.It Bq Er EACCES
				Search permission is denied for the component of the path prefix of
				.Fa filename
				or read permission is denied for
				.Fa filename .
				.It Bq Er ELOOP
				A loop exists in symbolic links encountered during resolution of the
				.Fa filename
				argument.
				.It Bq Er ENAMETOOLONG
				The length of the
				.Fa filename
				argument exceeds
				.Brq Dv PATH_MAX
				or
				a pathname component is longer than
				.Brq Dv NAME_MAX .
				.It Bq Er ENOENT
				A component of
				.Fa filename
				does not name an existing directory or
				.Fa filename
				is an empty string.
				.It Bq Er ENOTDIR
				A component of
				.Fa filename
				is not a directory.
				.El
				.Pp
				The
				.Fn fdopendir
				function will fail if:
				.Bl -tag -width Er
				.It Bq Er EBADF
				The
				.Fa fd
				argument is not a valid file descriptor open for reading.
				.It Bq Er ENOTDIR
				The descriptor
				.Fa fd
				is not associated with a directory.
				.El
				.Pp
				The
				.Fn readdir
				and
				.Fn readdir_r
				functions may also fail and set
				.Va errno
				for any of the errors specified for the routine
				.Xr getdents 2 .
				.Pp
				The
				.Fn telldir
				function may also fail and set
				.Va errno
				for any of the errors specified for the routine
				.Xr realloc 3 .
				.Pp
				The
				.Fn closedir
				function may also fail and set
				.Va errno
				for any of the errors specified for the routine
				.Xr close 2 .
	.Sh SEE ALSO			.Sh SEE ALSO
	.Xr close 2 ,			.Xr close 2 ,
	.Xr lseek 2 ,			.Xr lseek 2 ,
	.Xr open 2 ,			.Xr open 2 ,
	.Xr read 2 ,			.Xr read 2 ,
	.Xr dir 5			.Xr dir 5
	.Sh STANDARDS			.Sh STANDARDS
	The			The
	▲ Show 20 Lines • Show All 65 Lines • Show Last 20 Lines