explain_telldir_or_die(3) [debian man page]

explain_telldir_or_die(3)				     Library Functions Manual					 explain_telldir_or_die(3)

NAME

       explain_telldir_or_die - current location in directory and report errors

SYNOPSIS

       #include <libexplain/telldir.h>
       off_t explain_telldir_or_die(DIR *dir);
       off_t explain_telldir_on_error(DIR *dir);

DESCRIPTION

       The  explain_telldir_or_die  function  is  used	to  call  the telldir(3) system call. On failure an explanation will be printed to stderr,
       obtained from the explain_telldir(3) function, and then the process terminates by calling exit(EXIT_FAILURE).

       The explain_telldir_on_error function is used to call the telldir(3) system call. On failure an explanation  will  be  printed  to  stderr,
       obtained from the explain_telldir(3) function, but still returns to the caller.

       dir     The dir, exactly as to be passed to the telldir(3) system call.

RETURN VALUE

       The  explain_telldir_or_die  function  only  returns on success, see telldir(3) for more information. On failure, prints an explanation and
       exits, it does not return.

       The explain_telldir_on_error function always returns the value return by the wrapped telldir(3) system call.

EXAMPLE

       The explain_telldir_or_die function is intended to be used in a fashion similar to the following example:
	      off_t result = explain_telldir_or_die(dir);

SEE ALSO

       telldir(3)
	       return current location in directory stream

       explain_telldir(3)
	       explain telldir(3) errors

       exit(2) terminate the calling process

COPYRIGHT

       libexplain version 0.52
       Copyright (C) 2009 Peter Miller

															 explain_telldir_or_die(3)

TELLDIR(3)						     Linux Programmer's Manual							TELLDIR(3)

NAME

       telldir - return current location in directory stream

SYNOPSIS

       #include <dirent.h>

       long telldir(DIR *dirp);

   Feature Test Macro Requirements for glibc (see feature_test_macros(7)):

       telldir():
	_XOPEN_SOURCE
	   || /* Glibc since 2.19: */ _DEFAULT_SOURCE
	   || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE

DESCRIPTION

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

RETURN VALUE

       On success, the telldir() function returns the current location in the directory stream.  On error, -1 is returned, and errno is set appro-
       priately.

ERRORS

       EBADF  Invalid directory stream descriptor dirp.

ATTRIBUTES

       For an explanation of the terms used in this section, see attributes(7).

       +----------+---------------+---------+
       |Interface | Attribute	  | Value   |
       +----------+---------------+---------+
       |telldir() | Thread safety | MT-Safe |
       +----------+---------------+---------+
CONFORMING TO

       POSIX.1-2001, POSIX.1-2008, 4.3BSD.

NOTES

       In glibc up to version 2.1.1, the return type of telldir() was off_t.  POSIX.1-2001 specifies long, and this is the type used  since  glibc
       2.1.2.

       In  early  filesystems,	the  value returned by telldir() was a simple file offset within a directory.  Modern filesystems use tree or hash
       structures, rather than flat tables, to represent directories.  On such filesystems, the value returned by telldir() (and  used	internally
       by readdir(3)) is a "cookie" that is used by the implementation to derive a position within a directory.  Application programs should treat
       this strictly as an opaque value, making no assumptions about its contents.

SEE ALSO

       closedir(3), opendir(3), readdir(3), rewinddir(3), scandir(3), seekdir(3)

COLOPHON

       This page is part of release 4.15 of the Linux man-pages project.  A description of the project, information about reporting bugs, and  the
       latest version of this page, can be found at https://www.kernel.org/doc/man-pages/.

								    2017-09-15								TELLDIR(3)