logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

alphasort.3p (6827B)


  1. '\" et
  2. .TH ALPHASORT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
  3. .\"
  4. .SH PROLOG
  5. This manual page is part of the POSIX Programmer's Manual.
  6. The Linux implementation of this interface may differ (consult
  7. the corresponding Linux manual page for details of Linux behavior),
  8. or the interface may not be implemented on Linux.
  9. .\"
  10. .SH NAME
  11. alphasort, scandir
  12. \(em scan a directory
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. #include <dirent.h>
  17. .P
  18. int alphasort(const struct dirent **\fId1\fP, const struct dirent **\fId2\fP);
  19. int scandir(const char *\fIdir\fP, struct dirent ***\fInamelist\fP,
  20. int (*\fIsel\fP)(const struct dirent *),
  21. int (*\fIcompar\fP)(const struct dirent **, const struct dirent **));
  22. .fi
  23. .SH DESCRIPTION
  24. The
  25. \fIalphasort\fR()
  26. function can be used as the comparison function for the
  27. \fIscandir\fR()
  28. function to sort the directory entries,
  29. .IR d1
  30. and
  31. .IR d2 ,
  32. into alphabetical order. Sorting happens as if by calling the
  33. \fIstrcoll\fR()
  34. function on the
  35. .IR d_name
  36. element of the
  37. .BR dirent
  38. structures passed as the two parameters. If the
  39. \fIstrcoll\fR()
  40. function fails, the return value of
  41. \fIalphasort\fR()
  42. is unspecified.
  43. .P
  44. The
  45. \fIalphasort\fR()
  46. function shall not change the setting of
  47. .IR errno
  48. if successful. Since no return value is reserved to indicate an error,
  49. an application wishing to check for error situations should set
  50. .IR errno
  51. to 0, then call
  52. \fIalphasort\fR(),
  53. then check
  54. .IR errno .
  55. .P
  56. The
  57. \fIscandir\fR()
  58. function shall scan the directory
  59. .IR dir ,
  60. calling the function referenced by
  61. .IR sel
  62. on each directory entry. Entries for which the function referenced by
  63. .IR sel
  64. returns non-zero shall be stored in strings allocated as if by
  65. a call to
  66. \fImalloc\fR(),
  67. and sorted as if by a call to
  68. \fIqsort\fR()
  69. with the comparison function
  70. .IR compar ,
  71. except that
  72. .IR compar
  73. need not provide total ordering. The strings are collected in
  74. array
  75. .IR namelist
  76. which shall be allocated as if by a call to
  77. \fImalloc\fR().
  78. If
  79. .IR sel
  80. is a null pointer, all entries shall be selected.
  81. If the comparison function
  82. .IR compar
  83. does not provide total ordering, the order in which the directory
  84. entries are stored is unspecified.
  85. .SH "RETURN VALUE"
  86. Upon successful completion, the
  87. \fIalphasort\fR()
  88. function shall return an integer greater than, equal to, or less than 0,
  89. according to whether the name of the directory entry pointed to by
  90. .IR d1
  91. is lexically greater than, equal to, or less than the directory pointed
  92. to by
  93. .IR d2
  94. when both are interpreted as appropriate to the current locale. There
  95. is no return value reserved to indicate an error.
  96. .P
  97. Upon successful completion, the
  98. \fIscandir\fR()
  99. function shall return the number of entries in the array and a pointer
  100. to the array through the parameter
  101. .IR namelist .
  102. Otherwise, the
  103. \fIscandir\fR()
  104. function shall return \-1.
  105. .SH ERRORS
  106. The
  107. \fIscandir\fR()
  108. function shall fail if:
  109. .TP
  110. .BR EACCES
  111. Search permission is denied for the component of the path prefix of
  112. .IR dir
  113. or read permission is denied for
  114. .IR dir .
  115. .TP
  116. .BR ELOOP
  117. A loop exists in symbolic links encountered during resolution of the
  118. .IR dir
  119. argument.
  120. .TP
  121. .BR ENAMETOOLONG
  122. .br
  123. The length of a component of a pathname is longer than
  124. {NAME_MAX}.
  125. .TP
  126. .BR ENOENT
  127. A component of
  128. .IR dir
  129. does not name an existing directory or
  130. .IR dir
  131. is an empty string.
  132. .TP
  133. .BR ENOMEM
  134. Insufficient storage space is available.
  135. .TP
  136. .BR ENOTDIR
  137. A component of
  138. .IR dir
  139. names an existing file that is neither a directory nor a symbolic link
  140. to a directory.
  141. .TP
  142. .BR EOVERFLOW
  143. One of the values to be returned or passed to a callback function cannot
  144. be represented correctly.
  145. .P
  146. The
  147. \fIscandir\fR()
  148. function may fail if:
  149. .TP
  150. .BR ELOOP
  151. More than
  152. {SYMLOOP_MAX}
  153. symbolic links were encountered during resolution of the
  154. .IR dir
  155. argument.
  156. .TP
  157. .BR EMFILE
  158. All file descriptors available to the process are currently open.
  159. .TP
  160. .BR ENAMETOOLONG
  161. .br
  162. The length of a pathname exceeds
  163. {PATH_MAX},
  164. or pathname resolution of a symbolic link produced an intermediate
  165. result with a length that exceeds
  166. {PATH_MAX}.
  167. .TP
  168. .BR ENFILE
  169. Too many files are currently open in the system.
  170. .LP
  171. .IR "The following sections are informative."
  172. .SH EXAMPLES
  173. An example to print the files in the current directory:
  174. .sp
  175. .RS 4
  176. .nf
  177. #include <dirent.h>
  178. #include <stdio.h>
  179. #include <stdlib.h>
  180. \&...
  181. struct dirent **namelist;
  182. int i,n;
  183. .P
  184. n = scandir(".", &namelist, 0, alphasort);
  185. if (n < 0)
  186. perror("scandir");
  187. else {
  188. for (i = 0; i < n; i++) {
  189. printf("%s\en", namelist[i]->d_name);
  190. free(namelist[i]);
  191. }
  192. }
  193. free(namelist);
  194. \&...
  195. .fi
  196. .P
  197. .RE
  198. .SH "APPLICATION USAGE"
  199. If
  200. .IR dir
  201. contains filenames that do not form character strings, or which contain
  202. characters outside the domain of the collating sequence of the current
  203. locale, the
  204. \fIalphasort\fR()
  205. function need not provide a total ordering. This condition is not possible
  206. if all filenames within the directory consist only of characters from
  207. the portable filename character set.
  208. .P
  209. The
  210. \fIscandir\fR()
  211. function may allocate dynamic storage during its operation. If
  212. \fIscandir\fR()
  213. is forcibly terminated, such as by
  214. \fIlongjmp\fR()
  215. or
  216. \fIsiglongjmp\fR()
  217. being executed by the function pointed to by
  218. .IR sel
  219. or
  220. .IR compar ,
  221. or by an interrupt routine,
  222. \fIscandir\fR()
  223. does not have a chance to free that storage, so it remains permanently
  224. allocated. A safe way to handle interrupts is to store the fact that
  225. an interrupt has occurred, then wait until
  226. \fIscandir\fR()
  227. returns to act on the interrupt.
  228. .P
  229. For functions that allocate memory as if by
  230. \fImalloc\fR(),
  231. the application should release such memory when it is no longer
  232. required by a call to
  233. \fIfree\fR().
  234. For
  235. \fIscandir\fR(),
  236. this is
  237. .IR namelist
  238. (including all of the individual strings in
  239. .IR namelist ).
  240. .SH RATIONALE
  241. None.
  242. .SH "FUTURE DIRECTIONS"
  243. None.
  244. .SH "SEE ALSO"
  245. .IR "\fIqsort\fR\^(\|)",
  246. .IR "\fIstrcoll\fR\^(\|)"
  247. .P
  248. The Base Definitions volume of POSIX.1\(hy2017,
  249. .IR "\fB<dirent.h>\fP"
  250. .\"
  251. .SH COPYRIGHT
  252. Portions of this text are reprinted and reproduced in electronic form
  253. from IEEE Std 1003.1-2017, Standard for Information Technology
  254. -- Portable Operating System Interface (POSIX), The Open Group Base
  255. Specifications Issue 7, 2018 Edition,
  256. Copyright (C) 2018 by the Institute of
  257. Electrical and Electronics Engineers, Inc and The Open Group.
  258. In the event of any discrepancy between this version and the original IEEE and
  259. The Open Group Standard, the original IEEE and The Open Group Standard
  260. is the referee document. The original Standard can be obtained online at
  261. http://www.opengroup.org/unix/online.html .
  262. .PP
  263. Any typographical or formatting errors that appear
  264. in this page are most likely
  265. to have been introduced during the conversion of the source files to
  266. man page format. To report such errors, see
  267. https://www.kernel.org/doc/man-pages/reporting_bugs.html .