diff options
Diffstat (limited to 'upstream/archlinux/man3p/alphasort.3p')
| -rw-r--r-- | upstream/archlinux/man3p/alphasort.3p | 268 |
1 files changed, 268 insertions, 0 deletions
diff --git a/upstream/archlinux/man3p/alphasort.3p b/upstream/archlinux/man3p/alphasort.3p new file mode 100644 index 00000000..3d595266 --- /dev/null +++ b/upstream/archlinux/man3p/alphasort.3p @@ -0,0 +1,268 @@ +'\" et +.TH ALPHASORT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +alphasort, scandir +\(em scan a directory +.SH SYNOPSIS +.LP +.nf +#include <dirent.h> +.P +int alphasort(const struct dirent **\fId1\fP, const struct dirent **\fId2\fP); +int scandir(const char *\fIdir\fP, struct dirent ***\fInamelist\fP, + int (*\fIsel\fP)(const struct dirent *), + int (*\fIcompar\fP)(const struct dirent **, const struct dirent **)); +.fi +.SH DESCRIPTION +The +\fIalphasort\fR() +function can be used as the comparison function for the +\fIscandir\fR() +function to sort the directory entries, +.IR d1 +and +.IR d2 , +into alphabetical order. Sorting happens as if by calling the +\fIstrcoll\fR() +function on the +.IR d_name +element of the +.BR dirent +structures passed as the two parameters. If the +\fIstrcoll\fR() +function fails, the return value of +\fIalphasort\fR() +is unspecified. +.P +The +\fIalphasort\fR() +function shall not change the setting of +.IR errno +if successful. Since no return value is reserved to indicate an error, +an application wishing to check for error situations should set +.IR errno +to 0, then call +\fIalphasort\fR(), +then check +.IR errno . +.P +The +\fIscandir\fR() +function shall scan the directory +.IR dir , +calling the function referenced by +.IR sel +on each directory entry. Entries for which the function referenced by +.IR sel +returns non-zero shall be stored in strings allocated as if by +a call to +\fImalloc\fR(), +and sorted as if by a call to +\fIqsort\fR() +with the comparison function +.IR compar , +except that +.IR compar +need not provide total ordering. The strings are collected in +array +.IR namelist +which shall be allocated as if by a call to +\fImalloc\fR(). +If +.IR sel +is a null pointer, all entries shall be selected. +If the comparison function +.IR compar +does not provide total ordering, the order in which the directory +entries are stored is unspecified. +.SH "RETURN VALUE" +Upon successful completion, the +\fIalphasort\fR() +function shall return an integer greater than, equal to, or less than 0, +according to whether the name of the directory entry pointed to by +.IR d1 +is lexically greater than, equal to, or less than the directory pointed +to by +.IR d2 +when both are interpreted as appropriate to the current locale. There +is no return value reserved to indicate an error. +.P +Upon successful completion, the +\fIscandir\fR() +function shall return the number of entries in the array and a pointer +to the array through the parameter +.IR namelist . +Otherwise, the +\fIscandir\fR() +function shall return \-1. +.SH ERRORS +The +\fIscandir\fR() +function shall fail if: +.TP +.BR EACCES +Search permission is denied for the component of the path prefix of +.IR dir +or read permission is denied for +.IR dir . +.TP +.BR ELOOP +A loop exists in symbolic links encountered during resolution of the +.IR dir +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a component of a pathname is longer than +{NAME_MAX}. +.TP +.BR ENOENT +A component of +.IR dir +does not name an existing directory or +.IR dir +is an empty string. +.TP +.BR ENOMEM +Insufficient storage space is available. +.TP +.BR ENOTDIR +A component of +.IR dir +names an existing file that is neither a directory nor a symbolic link +to a directory. +.TP +.BR EOVERFLOW +One of the values to be returned or passed to a callback function cannot +be represented correctly. +.P +The +\fIscandir\fR() +function may fail if: +.TP +.BR ELOOP +More than +{SYMLOOP_MAX} +symbolic links were encountered during resolution of the +.IR dir +argument. +.TP +.BR EMFILE +All file descriptors available to the process are currently open. +.TP +.BR ENAMETOOLONG +.br +The length of a pathname exceeds +{PATH_MAX}, +or pathname resolution of a symbolic link produced an intermediate +result with a length that exceeds +{PATH_MAX}. +.TP +.BR ENFILE +Too many files are currently open in the system. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +An example to print the files in the current directory: +.sp +.RS 4 +.nf + +#include <dirent.h> +#include <stdio.h> +#include <stdlib.h> +\&... +struct dirent **namelist; +int i,n; +.P + n = scandir(".", &namelist, 0, alphasort); + if (n < 0) + perror("scandir"); + else { + for (i = 0; i < n; i++) { + printf("%s\en", namelist[i]->d_name); + free(namelist[i]); + } + } + free(namelist); +\&... +.fi +.P +.RE +.SH "APPLICATION USAGE" +If +.IR dir +contains filenames that do not form character strings, or which contain +characters outside the domain of the collating sequence of the current +locale, the +\fIalphasort\fR() +function need not provide a total ordering. This condition is not possible +if all filenames within the directory consist only of characters from +the portable filename character set. +.P +The +\fIscandir\fR() +function may allocate dynamic storage during its operation. If +\fIscandir\fR() +is forcibly terminated, such as by +\fIlongjmp\fR() +or +\fIsiglongjmp\fR() +being executed by the function pointed to by +.IR sel +or +.IR compar , +or by an interrupt routine, +\fIscandir\fR() +does not have a chance to free that storage, so it remains permanently +allocated. A safe way to handle interrupts is to store the fact that +an interrupt has occurred, then wait until +\fIscandir\fR() +returns to act on the interrupt. +.P +For functions that allocate memory as if by +\fImalloc\fR(), +the application should release such memory when it is no longer +required by a call to +\fIfree\fR(). +For +\fIscandir\fR(), +this is +.IR namelist +(including all of the individual strings in +.IR namelist ). +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIqsort\fR\^(\|)", +.IR "\fIstrcoll\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB<dirent.h>\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . |