diff options
Diffstat (limited to 'manual')
| -rw-r--r-- | manual/examples/dir2.c | 29 | ||||
| -rw-r--r-- | manual/filesys.texi | 70 | ||||
| -rw-r--r-- | manual/math.texi | 12 |
3 files changed, 103 insertions, 8 deletions
diff --git a/manual/examples/dir2.c b/manual/examples/dir2.c new file mode 100644 index 0000000000..e3157694bd --- /dev/null +++ b/manual/examples/dir2.c @@ -0,0 +1,29 @@ +/*@group*/ +#include <stdio.h> +#include <dirent.h> +/*@end group*/ + +static int +one (struct dirent *unused) +{ + return 1; +} + +int +main (void) +{ + struct dirent **eps; + int n; + + n = scandir ("./", &eps, one, alphasort); + if (n >= 0) + { + int cnt; + for (cnt = 0; cnt < n; ++cnt) + puts (eps[cnt]->d_name); + } + else + perror ("Couldn't open the directory"); + + return 0; +} diff --git a/manual/filesys.texi b/manual/filesys.texi index f5d94b9732..afe072c594 100644 --- a/manual/filesys.texi +++ b/manual/filesys.texi @@ -166,6 +166,9 @@ parallels here to the stream facilities for ordinary files, described in * Simple Directory Lister:: A very simple directory listing program. * Random Access Directory:: Rereading part of the directory already read with the same stream. +* Scanning Directory Content:: Get entries for user selected subset of + contents in given directory. +* Simple Directory Lister Mark II:: Revised version of the program. @end menu @node Directory Entries @@ -386,9 +389,9 @@ the current working directory: The order in which files appear in a directory tends to be fairly random. A more useful program would sort the entries (perhaps by -alphabetizing them) before printing them; see @ref{Array Sort Function}. +alphabetizing them) before printing them; see +@ref{Scanning Directory Content} and @ref{Array Sort Function}. -@c ??? not documented: scandir, alphasort @node Random Access Directory @subsection Random Access in a Directory Stream @@ -429,6 +432,69 @@ closing and reopening the directory can invalidate values returned by @code{telldir}. @end deftypefun + +@node Scanning Directory Content +@subsection Scanning the Content of a Directory + +A higher-level interface to the directory handling functions is the +@code{scandir} function. With its help one can select a subset of the +entries in a directory, possibly sort them and get as the result a list +of names. + +@deftypefun int scandir (const char *@var{dir}, struct dirent ***@var{namelist}, int (*@var{selector}) (struct dirent *), int (*@var{cmp}) (const void *, const void *)) + +The @code{scandir} function scans the contents of the directory selected +by @var{dir}. The result in @var{namelist} is an array of pointers to +structure of type @code{struct dirent} which describe all selected +directory entries and which is allocated using @code{malloc}. Instead +of always getting all directory entries returned, the user supplied +function @var{selector} can be used to decide which entries are in the +result. Only the entries for which @var{selector} returns a nonzero +value are selected. + +Finally the entries in the @var{namelist} are sorted using the user +supplied function @var{cmp}. The arguments of the @var{cmp} function +are of type @code{struct dirent **}. I.e., one cannot directly use the +@code{strcmp} or @code{strcoll} function; see the function +@code{alphasort} below. + +The return value of the function gives the number of entries placed in +@var{namelist}. If it is @code{-1} an error occurred and the global +variable @code{errno} contains more information on the error. +@end deftypefun + +As said above the fourth argument to the @code{scandir} function must be +a pointer to a sorting function. For the convenience of the programmer +the GNU C library contains an implementation of a function which is very +helpful for this purpose. + +@deftypefun int alphasort (const void *@var{a}, const void *@var{b}) +The @code{alphasort} function behaves like the @code{strcmp} function +(@pxref{String/Array Comparison}). The difference is that the arguments +are not string pointers but instead they are of type +@code{struct dirent **}. + +Return value of is less than, equal to, or greater than zero depending +on the order of the two entries @var{a} and @var{b}. +@end deftypefun + +@node Simple Directory Lister Mark II +@subsection Simple Program to List a Directory, Mark II + +Here is a revised version of the directory lister found above +(@pxref{Simple Directory Lister}). Using the @code{scandir} function we +can avoid using the functions which directly work with the directory +contents. After the call the found entries are available for direct +used. + +@smallexample +@include dir2.c.texi +@end smallexample + +Please note the simple selector function for this example. Since +we want to see all directory entries we always return @code{1}. + + @node Hard Links @section Hard Links @cindex hard link diff --git a/manual/math.texi b/manual/math.texi index 61455ef8a8..543647297f 100644 --- a/manual/math.texi +++ b/manual/math.texi @@ -83,23 +83,23 @@ mathematical @code{double} returning functions in overflow situations. @end deftypevr @comment math.h -@comment GNU -@deftypevr Macro float HUGE_VALf +@comment ISO +@deftypevr Macro float HUGE_VALF This macro is similar to the @code{HUGE_VAL} macro except that it is used by functions returning @code{float} values. -This macro is a GNU extension. +This macro is introduced in @w{ISO C 9X}. @end deftypevr @comment math.h -@comment GNU -@deftypevr Macro {long double} HUGE_VALl +@comment ISO +@deftypevr Macro {long double} HUGE_VALL This macro is similar to the @code{HUGE_VAL} macro except that it is used by functions returning @code{long double} values. The value is only different from @code{HUGE_VAL} if the architecture really supports @code{long double} values. -This macro is a GNU extension. +This macro is introduced in @w{ISO C 9X}. @end deftypevr |