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

ls.1p (31842B)


  1. '\" et
  2. .TH LS "1P" 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. ls
  12. \(em list directory contents
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. ls \fB[\fR-ikqrs\fB] [\fR-g\|lno\|\fB] [\fR-A|-a\fB] [\fR-C|-m|-x|-1\fB]\fR \e
  17. \fB[\fR-F|-p\fB] [\fR-H|-L\fB] [\fR-R|-d\fB] [\fR-S|-f|-t\fB] [\fR-c|-u\fB] [\fIfile\fR...\fB]\fR
  18. .fi
  19. .SH DESCRIPTION
  20. For each operand that names a file of a type other than directory or
  21. symbolic link to a directory,
  22. .IR ls
  23. shall write the name of the file as well as any requested, associated
  24. information. For each operand that names a file of type directory,
  25. .IR ls
  26. shall write the names of files contained within the directory as well
  27. as any requested, associated information. Filenames beginning
  28. with a
  29. <period>
  30. (\c
  31. .BR '.' )
  32. and any associated information shall not be written out unless
  33. explicitly referenced, the
  34. .BR \-A
  35. or
  36. .BR \-a
  37. option is supplied, or an implementation-defined condition causes them
  38. to be written. If one or more of the
  39. .BR \-d ,
  40. .BR \-F ,
  41. or
  42. .BR \-l
  43. options are specified, and neither the
  44. .BR \-H
  45. nor the
  46. .BR \-L
  47. option is specified, for each operand that names a file of type
  48. symbolic link to a directory,
  49. .IR ls
  50. shall write the name of the file as well as any requested, associated
  51. information. If none of the
  52. .BR \-d ,
  53. .BR \-F ,
  54. or
  55. .BR \-l
  56. options are specified, or the
  57. .BR \-H
  58. or
  59. .BR \-L
  60. options are specified, for each operand that names a file of type
  61. symbolic link to a directory,
  62. .IR ls
  63. shall write the names of files contained within the directory as well
  64. as any requested, associated information. In each case where the names
  65. of files contained within a directory are written, if the directory
  66. contains any symbolic links then
  67. .IR ls
  68. shall evaluate the file information and file type to be those of
  69. the symbolic link itself, unless the
  70. .BR \-L
  71. option is specified.
  72. .P
  73. If no operands are specified,
  74. .IR ls
  75. shall behave as if a single operand of dot (\c
  76. .BR '.' )
  77. had been specified. If more than one operand is specified,
  78. .IR ls
  79. shall write non-directory operands first; it shall sort directory and
  80. non-directory operands separately according to the collating sequence
  81. in the current locale.
  82. .P
  83. Whenever
  84. .IR ls
  85. sorts filenames or pathnames according to the collating sequence in
  86. the current locale, if this collating sequence does not have a total
  87. ordering of all characters (see the Base Definitions volume of POSIX.1\(hy2017,
  88. .IR "Section 7.3.2" ", " "LC_COLLATE"),
  89. then any filenames or pathnames that collate equally should be further
  90. compared byte-by-byte using the collating sequence for the POSIX locale.
  91. .P
  92. The
  93. .IR ls
  94. utility shall detect infinite loops; that is, entering a previously
  95. visited directory that is an ancestor of the last file encountered.
  96. When it detects an infinite loop,
  97. .IR ls
  98. shall write a diagnostic message to standard error and shall either
  99. recover its position in the hierarchy or terminate.
  100. .SH OPTIONS
  101. The
  102. .IR ls
  103. utility shall conform to the Base Definitions volume of POSIX.1\(hy2017,
  104. .IR "Section 12.2" ", " "Utility Syntax Guidelines".
  105. .P
  106. The following options shall be supported:
  107. .IP "\fB\-A\fP" 10
  108. Write out all directory entries, including those whose names begin with a
  109. <period>
  110. (\c
  111. .BR '.' )
  112. but excluding the entries dot and dot-dot (if they exist).
  113. .IP "\fB\-C\fP" 10
  114. Write multi-text-column output with entries sorted down the columns,
  115. according to the collating sequence. The number of text columns and the
  116. column separator characters are unspecified, but should be adapted to
  117. the nature of the output device. This option disables long format output.
  118. .IP "\fB\-F\fP" 10
  119. Do not follow symbolic links named as operands unless the
  120. .BR \-H
  121. or
  122. .BR \-L
  123. options are specified. Write a
  124. <slash>
  125. (\c
  126. .BR '/' )
  127. immediately after each pathname that is a directory, an
  128. <asterisk>
  129. (\c
  130. .BR '*' )
  131. after each that is executable, a
  132. <vertical-line>
  133. (\c
  134. .BR '|' )
  135. after each that is a FIFO, and an at-sign (\c
  136. .BR '@' )
  137. after each that is a symbolic link. For other file types, other
  138. symbols may be written.
  139. .IP "\fB\-H\fP" 10
  140. Evaluate the file information and file type for symbolic links specified
  141. on the command line to be those of the file referenced by the link,
  142. and not the link itself; however,
  143. .IR ls
  144. shall write the name of the link itself and not the file referenced by
  145. the link.
  146. .IP "\fB\-L\fP" 10
  147. Evaluate the file information and file type for all symbolic links
  148. (whether named on the command line or encountered in a file hierarchy)
  149. to be those of the file referenced by the link, and not the link
  150. itself; however,
  151. .IR ls
  152. shall write the name of the link itself and not the file referenced by
  153. the link. When
  154. .BR \-L
  155. is used with
  156. .BR \-l ,
  157. write the contents of symbolic links in the long format (see the STDOUT
  158. section).
  159. .IP "\fB\-R\fP" 10
  160. Recursively list subdirectories encountered. When a symbolic link to a
  161. directory is encountered, the directory shall not be recursively listed
  162. unless the
  163. .BR \-L
  164. option is specified.
  165. The use of
  166. .BR \-R
  167. with
  168. .BR \-d
  169. or
  170. .BR \-f
  171. produces unspecified results.
  172. .IP "\fB\-S\fP" 10
  173. Sort with the primary key being file size (in decreasing order) and the
  174. secondary key being filename in the collating sequence (in increasing
  175. order).
  176. .IP "\fB\-a\fP" 10
  177. Write out all directory entries, including those whose names begin with a
  178. <period>
  179. (\c
  180. .BR '.' ).
  181. .IP "\fB\-c\fP" 10
  182. Use time of last modification of the file status information (see the Base Definitions volume of POSIX.1\(hy2017,
  183. .IR "\fB<sys_stat.h>\fP")
  184. instead of last modification of the file itself for sorting (\c
  185. .BR \-t )
  186. or writing (\c
  187. .BR \-l ).
  188. .IP "\fB\-d\fP" 10
  189. Do not follow symbolic links named as operands unless the
  190. .BR \-H
  191. or
  192. .BR \-L
  193. options are specified. Do not treat directories differently than other
  194. types of files. The use of
  195. .BR \-d
  196. with
  197. .BR \-R
  198. or
  199. .BR \-f
  200. produces unspecified results.
  201. .IP "\fB\-f\fP" 10
  202. List the entries in directory operands in the order they appear in the
  203. directory. The behavior for non-directory operands is unspecified. This
  204. option shall turn on
  205. .BR \-a .
  206. When
  207. .BR \-f
  208. is specified, any occurrences of the
  209. .BR \-r ,
  210. .BR \-S ,
  211. and
  212. .BR \-t
  213. options shall be ignored and any occurrences of the
  214. .BR \-A ,
  215. .BR \-g ,
  216. .BR \-l ,
  217. .BR \-n ,
  218. .BR \-o ,
  219. and
  220. .BR \-s
  221. options may be ignored. The use of
  222. .BR \-f
  223. with
  224. .BR \-R
  225. or
  226. .BR \-d
  227. produces unspecified results.
  228. .IP "\fB\-g\fP" 10
  229. Turn on the
  230. .BR \-l
  231. (ell) option, but disable writing the file's owner name or number.
  232. Disable the
  233. .BR \-C ,
  234. .BR \-m ,
  235. and
  236. .BR \-x
  237. options.
  238. .IP "\fB\-i\fP" 10
  239. For each file, write the file's file serial number (see
  240. \fIstat\fR()
  241. in the System Interfaces volume of POSIX.1\(hy2017).
  242. .IP "\fB\-k\fP" 10
  243. Set the block size for the
  244. .BR \-s
  245. option and the per-directory block count written for the
  246. .BR \-l ,
  247. .BR \-n ,
  248. .BR \-s ,
  249. .BR \-g ,
  250. and
  251. .BR \-o
  252. options (see the STDOUT section) to 1\|024 bytes.
  253. .IP "\fB\-l\fP" 10
  254. (The letter ell.) Do not follow symbolic links named as operands unless
  255. the
  256. .BR \-H
  257. or
  258. .BR \-L
  259. options are specified. Write out in long format (see the STDOUT
  260. section). Disable the
  261. .BR \-C ,
  262. .BR \-m ,
  263. and
  264. .BR \-x
  265. options.
  266. .IP "\fB\-m\fP" 10
  267. Stream output format; list pathnames across the page, separated by a
  268. <comma>
  269. character followed by a
  270. <space>
  271. character. Use a
  272. <newline>
  273. character as the list terminator and after the separator sequence when
  274. there is not room on a line for the next list entry. This option disables
  275. long format output.
  276. .IP "\fB\-n\fP" 10
  277. Turn on the
  278. .BR \-l
  279. (ell) option, but when writing the file's owner or group, write
  280. the file's numeric UID or GID rather than the user or group name,
  281. respectively. Disable the
  282. .BR \-C ,
  283. .BR \-m ,
  284. and
  285. .BR \-x
  286. options.
  287. .IP "\fB\-o\fP" 10
  288. Turn on the
  289. .BR \-l
  290. (ell) option, but disable writing the file's group name or number.
  291. Disable the
  292. .BR \-C ,
  293. .BR \-m ,
  294. and
  295. .BR \-x
  296. options.
  297. .IP "\fB\-p\fP" 10
  298. Write a
  299. <slash>
  300. (\c
  301. .BR '/' )
  302. after each filename if that file is a directory.
  303. .IP "\fB\-q\fP" 10
  304. Force each instance of non-printable filename characters and
  305. <tab>
  306. characters to be written as the
  307. <question-mark>
  308. (\c
  309. .BR '?' )
  310. character. Implementations may provide this option by default if the
  311. output is to a terminal device.
  312. .IP "\fB\-r\fP" 10
  313. Reverse the order of the sort to get reverse collating sequence oldest
  314. first, or smallest file size first depending on the other options
  315. given.
  316. .IP "\fB\-s\fP" 10
  317. Indicate the total number of file system blocks consumed by each file
  318. displayed. If the
  319. .BR \-k
  320. option is also specified, the block size shall be 1\|024 bytes;
  321. otherwise, the block size is implementation-defined.
  322. .IP "\fB\-t\fP" 10
  323. Sort with the primary key being time modified (most recently modified
  324. first) and the secondary key being filename in the collating sequence.
  325. For a symbolic link, the time used as the sort key is that of the
  326. symbolic link itself, unless
  327. .IR ls
  328. is evaluating its file information to be that of the file referenced
  329. by the link (see the
  330. .BR \-H
  331. and
  332. .BR \-L
  333. options).
  334. .IP "\fB\-u\fP" 10
  335. Use time of last access (see the Base Definitions volume of POSIX.1\(hy2017,
  336. .IR "\fB<sys_stat.h>\fP")
  337. instead of last modification of the file for sorting (\c
  338. .BR \-t )
  339. or writing (\c
  340. .BR \-l ).
  341. .IP "\fB\-x\fP" 10
  342. The same as
  343. .BR \-C ,
  344. except that the multi-text-column output is produced with entries sorted
  345. across, rather than down, the columns. This option disables long format
  346. output.
  347. .IP "\fB\-1\fP" 10
  348. (The numeric digit one.) Force output to be one entry per line.
  349. This option does not disable long format output. (Long format output is
  350. enabled by
  351. .BR \-g ,
  352. .BR \-l
  353. (ell),
  354. .BR \-n ,
  355. and
  356. .BR \-o ;
  357. and disabled by
  358. .BR \-C ,
  359. .BR \-m ,
  360. and
  361. .BR \-x .)
  362. .P
  363. If an option that enables long format output (\c
  364. .BR \-g ,
  365. .BR \-l
  366. (ell),
  367. .BR \-n ,
  368. and
  369. .BR "\\-o\|\" )
  370. is given with an option that disables long format output (\c
  371. .BR \-C ,
  372. .BR \-m ,
  373. and
  374. .BR \-x ),
  375. this shall not be considered an error. The last of these options
  376. specified shall determine whether long format output is written.
  377. .P
  378. If
  379. .BR \-R ,
  380. .BR \-d ,
  381. or
  382. .BR \-f
  383. are specified, the results of specifying these mutually-exclusive options
  384. are specified by the descriptions of these options above. If more
  385. than one of any of the other options shown in the SYNOPSIS section in
  386. mutually-exclusive sets are given, this shall not be considered an error;
  387. the last option specified in each set shall determine the output.
  388. .P
  389. Note that if
  390. .BR \-t
  391. is specified,
  392. .BR \-c
  393. and
  394. .BR \-u
  395. are not only mutually-exclusive with each other, they are also
  396. mutually-exclusive with
  397. .BR \-S
  398. when determining sort order. But even if
  399. .BR \-S
  400. is specified after all occurrences of
  401. .BR \-c ,
  402. .BR \-t ,
  403. and
  404. .BR \-u ,
  405. the last use of
  406. .BR \-c
  407. or
  408. .BR \-u
  409. determines the timestamp printed when producing long format output.
  410. .SH OPERANDS
  411. The following operand shall be supported:
  412. .IP "\fIfile\fR" 10
  413. A pathname of a file to be written. If the file specified is not
  414. found, a diagnostic message shall be output on standard error.
  415. .SH STDIN
  416. Not used.
  417. .SH "INPUT FILES"
  418. None.
  419. .br
  420. .SH "ENVIRONMENT VARIABLES"
  421. The following environment variables shall affect the execution of
  422. .IR ls :
  423. .IP "\fICOLUMNS\fP" 10
  424. Determine the user's preferred column position width for writing
  425. multiple text-column output. If this variable contains a string
  426. representing a decimal integer, the
  427. .IR ls
  428. utility shall calculate how many pathname text columns to write (see
  429. .BR \-C )
  430. based on the width provided. If
  431. .IR COLUMNS
  432. is not set or invalid, an implementation-defined number of column
  433. positions shall be assumed, based on the implementation's knowledge of
  434. the output device. The column width chosen to write the names of files
  435. in any given directory shall be constant. Filenames shall not be
  436. truncated to fit into the multiple text-column output.
  437. .IP "\fILANG\fP" 10
  438. Provide a default value for the internationalization variables that are
  439. unset or null. (See the Base Definitions volume of POSIX.1\(hy2017,
  440. .IR "Section 8.2" ", " "Internationalization Variables"
  441. for the precedence of internationalization variables used to determine
  442. the values of locale categories.)
  443. .IP "\fILC_ALL\fP" 10
  444. If set to a non-empty string value, override the values of all the
  445. other internationalization variables.
  446. .IP "\fILC_COLLATE\fP" 10
  447. .br
  448. Determine the locale for character collation information in determining
  449. the pathname collation sequence.
  450. .IP "\fILC_CTYPE\fP" 10
  451. Determine the locale for the interpretation of sequences of bytes of
  452. text data as characters (for example, single-byte as opposed to multi-byte
  453. characters in arguments) and which characters are defined as printable
  454. (character class
  455. .BR print ).
  456. .IP "\fILC_MESSAGES\fP" 10
  457. .br
  458. Determine the locale that should be used to affect the format and
  459. contents of diagnostic messages written to standard error.
  460. .IP "\fILC_TIME\fP" 10
  461. Determine the format and contents for date and time strings written by
  462. .IR ls .
  463. .IP "\fINLSPATH\fP" 10
  464. Determine the location of message catalogs for the processing of
  465. .IR LC_MESSAGES .
  466. .IP "\fITZ\fP" 10
  467. Determine the timezone for date and time strings written by
  468. .IR ls .
  469. If
  470. .IR TZ
  471. is unset or null, an unspecified default timezone shall be used.
  472. .SH "ASYNCHRONOUS EVENTS"
  473. Default.
  474. .SH STDOUT
  475. The default format shall be to list one entry per line to standard
  476. output; the exceptions are to terminals or when one of the
  477. .BR \-C ,
  478. .BR \-m ,
  479. or
  480. .BR \-x
  481. options is specified. If the output is to a terminal, the format is
  482. implementation-defined.
  483. .P
  484. When
  485. .BR \-m
  486. is specified, the format used for the last element of the list
  487. shall be:
  488. .sp
  489. .RS 4
  490. .nf
  491. "%s\en", <\fIfilename\fR>
  492. .fi
  493. .P
  494. .RE
  495. .P
  496. The format used for each other element of the list shall be:
  497. .sp
  498. .RS 4
  499. .nf
  500. "%s,%s", <\fIfilename\fR>, <\fIseparator\fR>
  501. .fi
  502. .P
  503. .RE
  504. .P
  505. where, if there is not room for the next element of the list to fit
  506. within the current line length, <\fIseparator\fP> is a string containing
  507. an optional
  508. <space>
  509. character and a mandatory
  510. <newline>
  511. character; otherwise it is a single
  512. <space>
  513. character.
  514. .P
  515. If the
  516. .BR \-i
  517. option is specified, the file's file serial number (see the Base Definitions volume of POSIX.1\(hy2017,
  518. .IR "\fB<sys_stat.h>\fP")
  519. shall be written in the following format before any other output for
  520. the corresponding entry:
  521. .sp
  522. .RS 4
  523. .nf
  524. %u ", <\fIfile serial number\fR>
  525. .fi
  526. .P
  527. .RE
  528. .P
  529. If the
  530. .BR \-l
  531. option is specified, the following information shall be written for
  532. files other than character special and block special files:
  533. .sp
  534. .RS 4
  535. .nf
  536. "%s %u %s %s %u %s %s\en", <\fIfile mode\fR>, <\fInumber of links\fR>,
  537. <\fIowner name\fR>, <\fIgroup name\fR>, <\fIsize\fR>, <\fIdate and time\fR>,
  538. <\fIpathname\fR>
  539. .fi
  540. .P
  541. .RE
  542. .P
  543. If the
  544. .BR \-l
  545. option is specified, the following information shall be written
  546. for character special and block special files:
  547. .sp
  548. .RS 4
  549. .nf
  550. "%s %u %s %s %s %s %s\en", <\fIfile mode\fR>, <\fInumber of links\fR>,
  551. <\fIowner name\fR>, <\fIgroup name\fR>, <\fIdevice info\fR>, <\fIdate and time\fR>,
  552. <\fIpathname\fR>
  553. .fi
  554. .P
  555. .RE
  556. .P
  557. In both cases if the file is a symbolic link and the
  558. .BR \-L
  559. option is also specified, this information shall be for the file
  560. resolved from the symbolic link, except that the <\fIpathname\fP> field
  561. shall contain the pathname of the symbolic link itself. If the file is
  562. a symbolic link and the
  563. .BR \-L
  564. option is not specified, this information shall be about the link itself
  565. and the <\fIpathname\fP> field shall be of the form:
  566. .sp
  567. .RS 4
  568. .nf
  569. "%s -> %s", <\fIpathname of link\fR>, <\fIcontents of link\fR>
  570. .fi
  571. .P
  572. .RE
  573. .P
  574. The
  575. .BR \-n ,
  576. .BR \-g ,
  577. and
  578. .BR \-o
  579. options use the same format as
  580. .BR \-l ,
  581. but with omitted items and their associated
  582. <blank>
  583. characters. See the OPTIONS section.
  584. .P
  585. In both the preceding
  586. .BR \-l
  587. forms, if <\fIowner name\fR> or <\fIgroup name\fR> cannot be
  588. determined, or if
  589. .BR \-n
  590. is given, they shall be replaced with their associated numeric values
  591. using the format
  592. .BR %u .
  593. .P
  594. The <\fIsize\fP> field shall contain the value that would be returned
  595. for the file in the
  596. .IR st_size
  597. field of
  598. .BR "struct stat"
  599. (see the Base Definitions volume of POSIX.1\(hy2017,
  600. .IR "\fB<sys_stat.h>\fP").
  601. Note that for some file types this value is unspecified.
  602. .P
  603. The <\fIdevice\ info\fP> field shall contain implementation-defined
  604. information associated with the device in question.
  605. .P
  606. The <\fIdate\ and\ time\fP> field shall contain the appropriate date
  607. and timestamp of when the file was last modified. In the POSIX locale,
  608. the field shall be the equivalent of the output of the following
  609. .IR date
  610. command:
  611. .sp
  612. .RS 4
  613. .nf
  614. date "+%b %e %H:%M"
  615. .fi
  616. .P
  617. .RE
  618. .P
  619. if the file has been modified in the last six months, or:
  620. .sp
  621. .RS 4
  622. .nf
  623. date "+%b %e %Y"
  624. .fi
  625. .P
  626. .RE
  627. .P
  628. (where two
  629. <space>
  630. characters are used between
  631. .BR %e
  632. and
  633. .BR %Y )
  634. if the file has not been modified in the last six months or if the
  635. modification date is in the future, except that, in both cases, the final
  636. <newline>
  637. produced by
  638. .IR date
  639. shall not be included and the output shall be as if the
  640. .IR date
  641. command were executed at the time of the last modification date of the
  642. file rather than the current time. When the
  643. .IR LC_TIME
  644. locale category is not set to the POSIX locale, a different format and
  645. order of presentation of this field may be used.
  646. .P
  647. If the pathname was specified as a
  648. .IR file
  649. operand, it shall be written as specified.
  650. .P
  651. The file mode written under the
  652. .BR \-l ,
  653. .BR \-n ,
  654. .BR \-g ,
  655. and
  656. .BR \-o
  657. options shall consist of the following format:
  658. .sp
  659. .RS 4
  660. .nf
  661. "%c%s%s%s%s", <\fIentry type\fR>, <\fIowner permissions\fR>,
  662. <\fIgroup permissions\fR>, <\fIother permissions\fR>,
  663. <\fIoptional alternate access method flag\fR>
  664. .fi
  665. .P
  666. .RE
  667. .P
  668. The <\fIoptional\ alternate\ access\ method\ flag\fP> shall be the
  669. empty string if there is no alternate or additional access control
  670. method associated with the file; otherwise, it shall be a string
  671. containing a single printable character that is not a
  672. <blank>.
  673. .P
  674. The <\fIentry\ type\fP> character shall describe the type of file, as
  675. follows:
  676. .IP "\fRd\fP" 8
  677. Directory.
  678. .IP "\fRb\fP" 8
  679. Block special file.
  680. .IP "\fRc\fP" 8
  681. Character special file.
  682. .IP "\fRl\fP\ (ell)" 8
  683. Symbolic link.
  684. .IP "\fRp\fP" 8
  685. FIFO.
  686. .IP "\fR\-\fP" 8
  687. Regular file.
  688. .P
  689. Implementations may add other characters to this list to represent
  690. other implementation-defined file types.
  691. .P
  692. The next three fields shall be three characters each:
  693. .IP "<\fIowner permissions\fP>" 6
  694. .br
  695. Permissions for the file owner class (see the Base Definitions volume of POSIX.1\(hy2017,
  696. .IR "Section 4.5" ", " "File Access Permissions").
  697. .IP "<\fIgroup permissions\fP>" 6
  698. .br
  699. Permissions for the file group class.
  700. .IP "<\fIother permissions\fP>" 6
  701. .br
  702. Permissions for the file other class.
  703. .P
  704. Each field shall have three character positions:
  705. .IP " 1." 4
  706. If
  707. .BR 'r' ,
  708. the file is readable; if
  709. .BR '\-' ,
  710. the file is not readable.
  711. .IP " 2." 4
  712. If
  713. .BR 'w' ,
  714. the file is writable; if
  715. .BR '\-' ,
  716. the file is not writable.
  717. .IP " 3." 4
  718. The first of the following that applies:
  719. .RS 4
  720. .IP "\fRS\fR" 6
  721. If in <\fIowner\ permissions\fP>, the file is not executable and
  722. set-user-ID mode is set. If in <\fIgroup\ permissions\fP>, the file is
  723. not executable and set-group-ID mode is set.
  724. .IP "\fRs\fR" 6
  725. If in <\fIowner\ permissions\fP>, the file is executable and
  726. set-user-ID mode is set. If in <\fIgroup\ permissions\fP>, the file is
  727. executable and set-group-ID mode is set.
  728. .IP "\fRT\fR" 6
  729. If in <\fIother\ permissions\fP> and the file is a directory, search
  730. permission is not granted to others, and the restricted deletion flag
  731. is set.
  732. .IP "\fRt\fR" 6
  733. If in <\fIother\ permissions\fP> and the file is a directory, search
  734. permission is granted to others, and the restricted deletion flag
  735. is set.
  736. .IP "\fRx\fR" 6
  737. The file is executable or the directory is searchable.
  738. .IP "\fR\-\fR" 6
  739. None of the attributes of
  740. .BR 'S' ,
  741. .BR 's' ,
  742. .BR 'T' ,
  743. .BR 't' ,
  744. or
  745. .BR 'x'
  746. applies.
  747. .P
  748. Implementations may add other characters to this list for the third
  749. character position. Such additions shall, however, be written in
  750. lowercase if the file is executable or searchable, and in uppercase if
  751. it is not.
  752. .RE
  753. .P
  754. If any of the
  755. .BR \-l ,
  756. .BR \-n ,
  757. .BR \-s ,
  758. .BR \-g ,
  759. or
  760. .BR \-o
  761. options is specified, each list of files within the directory shall be
  762. preceded by a status line indicating the number of file system blocks
  763. occupied by files in the directory in 512-byte units if the
  764. .BR \-k
  765. option is not specified, or 1\|024-byte units if the
  766. .BR \-k
  767. option is specified, rounded up to the next integral number of units,
  768. if necessary. In the POSIX locale, the format shall be:
  769. .sp
  770. .RS 4
  771. .nf
  772. "total %u\en", <\fInumber of units in the directory\fR>
  773. .fi
  774. .P
  775. .RE
  776. .P
  777. If more than one directory, or a combination of non-directory files and
  778. directories are written, either as a result of specifying multiple
  779. operands, or the
  780. .BR \-R
  781. option, each list of files within a directory shall be preceded by:
  782. .sp
  783. .RS 4
  784. .nf
  785. "\en%s:\en", <\fIdirectory name\fR>
  786. .fi
  787. .P
  788. .RE
  789. .P
  790. If this string is the first thing to be written, the first
  791. <newline>
  792. shall not be written. This output shall precede the number of units in
  793. the directory.
  794. .P
  795. If the
  796. .BR \-s
  797. option is given, each file shall be written with the number of blocks
  798. used by the file. Along with
  799. .BR \-C ,
  800. .BR \-1 ,
  801. .BR \-m ,
  802. or
  803. .BR \-x ,
  804. the number and a
  805. <space>
  806. shall precede the filename; with
  807. .BR \-l ,
  808. .BR \-n ,
  809. .BR \-g ,
  810. or
  811. .BR \-o ,
  812. they shall precede each line describing a file.
  813. .SH STDERR
  814. The standard error shall be used only for diagnostic messages.
  815. .SH "OUTPUT FILES"
  816. None.
  817. .SH "EXTENDED DESCRIPTION"
  818. None.
  819. .SH "EXIT STATUS"
  820. The following exit values shall be returned:
  821. .IP "\00" 6
  822. Successful completion.
  823. .IP >0 6
  824. An error occurred.
  825. .SH "CONSEQUENCES OF ERRORS"
  826. Default.
  827. .LP
  828. .IR "The following sections are informative."
  829. .SH "APPLICATION USAGE"
  830. Many implementations use the
  831. <equals-sign>
  832. (\c
  833. .BR '=' )
  834. to denote sockets bound to the file system for the
  835. .BR \-F
  836. option. Similarly, many historical implementations use the
  837. .BR 's'
  838. character to denote sockets as the entry type characters for the
  839. .BR \-l
  840. option.
  841. .P
  842. It is difficult for an application to use every part of the file modes
  843. field of
  844. .IR ls
  845. .BR \-l
  846. in a portable manner. Certain file types and executable bits are not
  847. guaranteed to be exactly as shown, as implementations may have
  848. extensions. Applications can use this field to pass directly to a user
  849. printout or prompt, but actions based on its contents should generally
  850. be deferred, instead, to the
  851. .IR test
  852. utility.
  853. .P
  854. The output of
  855. .IR ls
  856. (with the
  857. .BR \-l
  858. and related options) contains information that logically could be used
  859. by utilities such as
  860. .IR chmod
  861. and
  862. .IR touch
  863. to restore files to a known state. However, this information is
  864. presented in a format that cannot be used directly by those utilities
  865. or be easily translated into a format that can be used. A character
  866. has been added to the end of the permissions string so that
  867. applications at least have an indication that they may be working in an
  868. area they do not understand instead of assuming that they can translate
  869. the permissions string into something that can be used. Future versions
  870. or related documents may define one or more specific characters to be
  871. used based on different standard additional or alternative access
  872. control mechanisms.
  873. .P
  874. As with many of the utilities that deal with filenames, the output of
  875. .IR ls
  876. for multiple files or in one of the long listing formats must be used
  877. carefully on systems where filenames can contain embedded white
  878. space. Systems and system administrators should institute policies and
  879. user training to limit the use of such filenames.
  880. .P
  881. The number of disk blocks occupied by the file that it reports varies
  882. depending on underlying file system type, block size units reported,
  883. and the method of calculating the number of blocks. On some file
  884. system types, the number is the actual number of blocks occupied by the
  885. file (counting indirect blocks and ignoring holes in the file); on
  886. others it is calculated based on the file size (usually making an
  887. allowance for indirect blocks, but ignoring holes).
  888. .SH EXAMPLES
  889. An example of a small directory tree being fully listed with
  890. .IR ls
  891. .BR "\-laRF\ a"
  892. in the POSIX locale:
  893. .sp
  894. .RS 4
  895. .nf
  896. total 11
  897. drwxr-xr-x 3 fox prog 64 Jul 4 12:07 ./
  898. drwxrwxrwx 4 fox prog 3264 Jul 4 12:09 ../
  899. drwxr-xr-x 2 fox prog 48 Jul 4 12:07 b/
  900. -rwxr--r-- 1 fox prog 572 Jul 4 12:07 foo*
  901. .P
  902. a/b:
  903. total 4
  904. drwxr-xr-x 2 fox prog 48 Jul 4 12:07 ./
  905. drwxr-xr-x 3 fox prog 64 Jul 4 12:07 ../
  906. -rw-r--r-- 1 fox prog 700 Jul 4 12:07 bar
  907. .fi
  908. .P
  909. .RE
  910. .SH RATIONALE
  911. Some historical implementations of the
  912. .IR ls
  913. utility show all entries in a directory except dot and dot-dot when a
  914. superuser invokes
  915. .IR ls
  916. without specifying the
  917. .BR \-a
  918. option. When ``normal'' users invoke
  919. .IR ls
  920. without specifying
  921. .BR \-a ,
  922. they should not see information about any files with names beginning
  923. with a
  924. <period>
  925. unless they were named as
  926. .IR file
  927. operands.
  928. .P
  929. Implementations are expected to traverse arbitrary depths when
  930. processing the
  931. .BR \-R
  932. option. The only limitation on depth should be based on running out of
  933. physical storage for keeping track of untraversed directories.
  934. .P
  935. The
  936. .BR \-1
  937. (one) option was historically found in BSD and BSD-derived
  938. implementations only. It is required in this volume of POSIX.1\(hy2017 so that conforming
  939. applications might ensure that output is one entry per line, even if
  940. the output is to a terminal.
  941. .P
  942. The
  943. .BR \-S
  944. option was added in Issue 7, but had been provided by several
  945. implementations for many years. The description given in the
  946. standard documents historic practice, but does not match much of the
  947. documentation that described its behavior. Historical documentation
  948. typically described it as something like:
  949. .IP "\fB\-S\fP" 10
  950. Sort by size (largest size first) instead of by name. Special character
  951. devices (listed last) are sorted by name.
  952. .P
  953. even though the file type was never considered when sorting the output.
  954. Character special files do typically sort close to the end of the list
  955. because their file size on most implementations is zero. But they are
  956. sorted alphabetically with any other files that happen to have the same
  957. file size (zero), not sorted separately and added to the end.
  958. .P
  959. This volume of POSIX.1\(hy2017 is frequently silent about what happens when mutually-exclusive
  960. options are specified. Except for
  961. .BR \-R ,
  962. .BR \-d ,
  963. and
  964. .BR \-f ,
  965. the
  966. .IR ls
  967. utility is required to accept multiple options from each
  968. mutually-exclusive option set without treating them as errors and to use
  969. the behavior specified by the last option given in each mutually-exclusive
  970. set. Since
  971. .IR ls
  972. is one of the most aliased commands, it is important that the
  973. implementation perform intuitively. For example, if the alias were:
  974. .sp
  975. .RS 4
  976. .nf
  977. alias ls="ls -C"
  978. .fi
  979. .P
  980. .RE
  981. .P
  982. and the user typed
  983. .IR ls
  984. .BR \-1
  985. (one), single-text-column output should result, not an error.
  986. .P
  987. The
  988. .BR \-g ,
  989. .BR \-l
  990. (ell),
  991. .BR \-n ,
  992. and
  993. .BR \-o
  994. options are not mutually-exclusive options. They all enable long format
  995. output. They work together to determine whether the file's owner is
  996. written (no if
  997. .BR \-g
  998. is present), file's group is written (no if
  999. .BR \-o
  1000. is present), and if the file's group or owner is written whether it is
  1001. written as the name (default) or a string representation of the UID or
  1002. GID number (if
  1003. .BR \-n
  1004. is present). The
  1005. .BR \-C ,
  1006. .BR \-m ,
  1007. .BR \-x ,
  1008. and
  1009. .BR \-1
  1010. (one) are mutually-exclusive options and the first three of these disable
  1011. long format output. The
  1012. .BR \-1
  1013. (one) option does not directly change whether or not long format output
  1014. is enabled, but by overriding
  1015. .BR \-C ,
  1016. .BR \-m ,
  1017. and
  1018. .BR \-x ,
  1019. it can re-enable long format output that had been disabled by one of
  1020. these options.
  1021. .P
  1022. Earlier versions of this standard did not describe the BSD
  1023. .BR \-A
  1024. option (like
  1025. .BR \-a ,
  1026. but dot and dot-dot are not written out). It has been added due to
  1027. widespread implementation.
  1028. .P
  1029. Implementations may make
  1030. .BR \-q
  1031. the default for terminals to prevent trojan horse attacks on terminals
  1032. with special escape sequences.
  1033. This is not required because:
  1034. .IP " *" 4
  1035. Some control characters may be useful on some terminals; for example, a
  1036. system might write them as
  1037. .BR \(dq\e001\(dq
  1038. or
  1039. .BR \(dq\(haA\(dq .
  1040. .IP " *" 4
  1041. Special behavior for terminals is not relevant to applications
  1042. portability.
  1043. .P
  1044. An early proposal specified that the
  1045. <\fIoptional\ alternate\ access\ method\ flag\fR> had to be
  1046. .BR '\(pl'
  1047. if there was an alternate access method used on the file or
  1048. <space>
  1049. if there was not. This was changed to be
  1050. <space>
  1051. if there is not and a single printable character if there is. This was
  1052. done for three reasons:
  1053. .IP " 1." 4
  1054. There are historical implementations using characters other than
  1055. .BR '\(pl' .
  1056. .IP " 2." 4
  1057. There are implementations that vary this character used in that
  1058. position to distinguish between various alternate access methods in
  1059. use.
  1060. .IP " 3." 4
  1061. The standard developers did not want to preclude future specifications
  1062. that might need a way to specify more than one alternate access
  1063. method.
  1064. .P
  1065. Nonetheless, implementations providing a single alternate access method
  1066. are encouraged to use
  1067. .BR '\(pl' .
  1068. .P
  1069. Earlier versions of this standard did not have the
  1070. .BR \-k
  1071. option, which meant that the
  1072. .BR \-s
  1073. option could not be used portably as its block size was
  1074. implementation-defined, and the units used to specify the
  1075. number of blocks occupied by files in a directory in an
  1076. .IR ls
  1077. .BR \-l
  1078. listing were fixed as 512-byte units. The
  1079. .BR \-k
  1080. option has been added to provide a way for the
  1081. .BR \-s
  1082. option to be used portably, and for consistency it also changes the
  1083. aforementioned units from 512-byte to 1\|024-byte.
  1084. .P
  1085. The <\fIdate\ and\ time\fP> field in the
  1086. .BR \-l
  1087. format is specified only for the POSIX locale. As noted, the format can
  1088. be different in other locales. No mechanism for defining this is
  1089. present in this volume of POSIX.1\(hy2017, as the appropriate vehicle is a messaging system;
  1090. that is, the format should be specified as a ``message''.
  1091. .SH "FUTURE DIRECTIONS"
  1092. Allowing
  1093. .BR \-f
  1094. to ignore the
  1095. .BR \-A ,
  1096. .BR \-g ,
  1097. .BR \-l ,
  1098. .BR \-n ,
  1099. .BR \-o ,
  1100. and
  1101. .BR \-s
  1102. options may be removed in a future version.
  1103. .P
  1104. A future version of this standard may require that if the collating
  1105. sequence for the current locale does not have a total ordering of all
  1106. characters, any filenames or pathnames that collate equally are
  1107. further compared byte-by-byte using the collating sequence for the
  1108. POSIX locale.
  1109. .SH "SEE ALSO"
  1110. .IR "\fIchmod\fR\^",
  1111. .IR "\fIfind\fR\^"
  1112. .P
  1113. The Base Definitions volume of POSIX.1\(hy2017,
  1114. .IR "Section 7.3.2" ", " "LC_COLLATE",
  1115. .IR "Section 4.5" ", " "File Access Permissions",
  1116. .IR "Chapter 8" ", " "Environment Variables",
  1117. .IR "Section 12.2" ", " "Utility Syntax Guidelines",
  1118. .IR "\fB<sys_stat.h>\fP"
  1119. .P
  1120. The System Interfaces volume of POSIX.1\(hy2017,
  1121. .IR "\fIfstatat\fR\^(\|)"
  1122. .\"
  1123. .SH COPYRIGHT
  1124. Portions of this text are reprinted and reproduced in electronic form
  1125. from IEEE Std 1003.1-2017, Standard for Information Technology
  1126. -- Portable Operating System Interface (POSIX), The Open Group Base
  1127. Specifications Issue 7, 2018 Edition,
  1128. Copyright (C) 2018 by the Institute of
  1129. Electrical and Electronics Engineers, Inc and The Open Group.
  1130. In the event of any discrepancy between this version and the original IEEE and
  1131. The Open Group Standard, the original IEEE and The Open Group Standard
  1132. is the referee document. The original Standard can be obtained online at
  1133. http://www.opengroup.org/unix/online.html .
  1134. .PP
  1135. Any typographical or formatting errors that appear
  1136. in this page are most likely
  1137. to have been introduced during the conversion of the source files to
  1138. man page format. To report such errors, see
  1139. https://www.kernel.org/doc/man-pages/reporting_bugs.html .