> For the complete documentation index, see [llms.txt](https://book.bsdcn.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://book.bsdcn.org/man/man1/ls.1.md).

# ls.1

`ls` — 列出目录内容

## 名称

`ls`

## 概要

`ls [-ABCFGHILPRSTUWZabcdfghiklmnopqrstuvwxy1,] [--color=when] [--group-directories=order] [--group-directories-first] [-D format] [file]`

## 描述

对于每个命名了非目录类型 `file` 的操作数，`ls` 显示其名称以及任何请求的相关信息。对于每个命名了目录类型 `file` 的操作数，`ls` 显示该目录中包含的文件名称，以及任何请求的相关信息。

如果未给定操作数，则显示当前目录的内容。如果给定了多个操作数，非目录操作数先显示；目录和非目录操作数分别排序，并按字典顺序排列。

可用选项如下：

**`-A`** 包含名称以点（‘`.`’）开头的目录项，但不包括 `.` 和 `..`。对超级用户自动设置，除非指定了 `-I`。

**`-B`** 强制以 `\exxx` 的形式打印文件名中的不可打印字符（由 ctype(3) 和当前 locale 设置定义），其中 `xxx` 是字符的八进制数值。此选项未在 IEEE Std 1003.1-2008 ("POSIX.1") 中定义。

**`-C`** 强制多列输出；这是输出到终端时的默认行为。

**`-D`** `format` 以长（`-l`）格式打印时，使用 `format` 来格式化日期和时间输出。参数 `format` 是一个由 strftime(3) 使用的字符串。根据格式字符串的选择，输出中的列数可能不同。此选项覆盖 `-T` 选项。此选项未在 IEEE Std 1003.1-2008 ("POSIX.1") 中定义。

**`-F`** 在每个作为目录的路径名后紧跟着显示斜杠（`/`），在每个可执行文件后显示星号（`*`），在每个符号链接后显示 at 符号（`@`），在每个套接字后显示等号（`=`），在每个 whiteout 后显示百分号（`%`），在每个 FIFO 后显示竖线（`|`）。

**`-G`** 启用彩色输出。此选项等效于在环境中定义 `CLICOLOR` 或 `COLORTERM` 并设置 `--color`=`auto`。（参见下文。）通过移除 `COLORLS` 的定义可在编译时禁用此功能。此选项未在 IEEE Std 1003.1-2008 ("POSIX.1") 中定义。

**`-H`** 命令行上的符号链接会被跟随。如果未指定 `-F`、`-d` 或 `-l` 选项中的任何一个，则假定此选项。

**`-I`** 阻止对超级用户自动设置 `-A`。此选项未在 IEEE Std 1003.1-2008 ("POSIX.1") 中定义。

**`-L`** 如果参数是符号链接，列出链接所引用的文件或目录，而非链接本身。此选项取消 `-P` 选项。

**`-P`** 如果参数是符号链接，列出链接本身，而非链接所引用的对象。此选项取消 `-H` 和 `-L` 选项。

**`-R`** 递归列出遇到的子目录。

**`-S`** 在按字典顺序排序操作数之前，先按大小排序（最大的文件优先）。

**`-T`** 以长（`-l`）格式打印时，显示文件的完整时间信息，包括月、日、时、分、秒和年。`-D` 选项对输出格式提供更多控制。此选项未在 IEEE Std 1003.1-2008 ("POSIX.1") 中定义。

**`-U`** 使用文件创建时间进行排序或打印。此选项未在 IEEE Std 1003.1-2008 ("POSIX.1") 中定义。

**`-W`** 扫描目录时显示 whiteout。此选项未在 IEEE Std 1003.1-2008 ("POSIX.1") 中定义。

**`-Z`** 显示每个文件的 MAC 标签；参见 [maclabel(7)](https://github.com/FreeBSD-Ask/freebsd-man-sc/blob/main/man7/maclabel.7.md)。此选项未在 IEEE Std 1003.1-2008 ("POSIX.1") 中定义。

**`-a`** 包含名称以点（‘`.`’）开头的目录项。

**`-b`** 与 `-B` 相同，但尽可能使用 C 转义码。此选项未在 IEEE Std 1003.1-2008 ("POSIX.1") 中定义。

**`-c`** 使用文件状态最后更改的时间进行排序或打印。

**`--color`**=`when` 根据 `when` 输出彩色转义序列，`when` 可设置为 `always`、`auto` 或 `never`。`always` 使 `ls` 始终输出颜色。如果 `TERM` 未设置或设置为无效终端，则 `ls` 将回退到不带 termcap(5) 帮助的显式 ANSI 转义序列。如果指定了 `--color` 但未带参数，则默认为 `always`。`auto` 使 `ls` 基于 termcap(5) 输出转义序列，但仅当 `stdout` 是 tty 且指定了 `-G` 标志或环境变量 `COLORTERM` 或 `CLICOLOR` 之一被设置且非空时。`never` 无论环境变量如何都禁用颜色。当未指定 `--color` 和 `-G` 时默认为 `never`。为与 GNU coreutils 兼容，`ls` 支持 `yes` 或 `force` 等效于 `always`，`no` 或 `none` 等效于 `never`，`tty` 或 `if-tty` 等效于 `auto`。

**`-d`** 目录作为普通文件列出（不递归搜索）。

**`-f`** 输出不排序。此选项开启 `-a`。它还抵消 `-r`、`-S` 和 `-t` 选项的效果。根据 IEEE Std 1003.1-2008 ("POSIX.1") 的允许，此选项对 `-d`、`-l`、`-R` 和 `-s` 选项无效。

**`-g`** 显示长（`-l`）格式输出，但不显示文件所有者的名称或编号。

**`--group-directories`**=`order` 在每个操作数的结果中，将目录分组在一起，并按 `first` 或 `last` 打印。

**`--group-directories-first`** 等效于 `--group-directories`=`first`。为与 GNU coreutils 兼容而实现。

**`-h`** 与 `-l` 选项一起使用时，使用单位后缀：Byte、Kilobyte、Megabyte、Gigabyte、Terabyte 和 Petabyte，以 base 2 为基础将数字位数减少到四位或更少。此选项未在 IEEE Std 1003.1-2008 ("POSIX.1") 中定义。

**`-i`** 对每个文件，打印文件的文件序列号（inode 编号）。

**`-k`** 这与将环境变量 `BLOCKSIZE` 设置为 1024 的效果相同，但它还会使其左侧的任何 `-h` 选项失效。

**`-l`** （小写字母“ell”。）以长格式列出文件，如下文“长格式”小节所述。

**`-m`** 流式输出格式；跨页面列出文件，以逗号分隔。

**`-n`** 在长（`-l`）输出中，以数字形式显示用户和组 ID，而非转换为用户或组名。

**`-o`** 在长（`-l`）输出中包含文件标志。此选项与 IEEE Std 1003.1-2008 ("POSIX.1") 不兼容。有关文件标志及其含义的列表，参见 chflags(1)。

**`-p`** 如果文件是目录，则在每个文件名后写入斜杠（`/`）。

**`-q`** 强制将文件名中的非图形字符打印为字符 `?`；这是输出到终端时的默认行为。

**`-r`** 反转排序顺序。

**`-s`** 显示每个文件在文件系统中使用的块数。块大小和目录总数按下文“长格式”小节所述处理，但（如果未同时请求长格式）当输出为单列时，即使请求多列输出，也不输出目录总数。

**`-t`** 按修改时间降序排序（最近修改的优先）。如果两个文件具有相同的修改时间戳，则按字典升序排序其名称。`-r` 选项反转这两种排序顺序。注意，这些排序顺序是矛盾的：时间序列按降序排列，字典排序按升序排列。此行为由 IEEE Std 1003.2 ("POSIX.2") 规定。此功能可能导致列出以顺序名称存储在 FAT 文件系统上的文件时出现问题，例如来自数码相机的文件，其中可能有多张具有相同时间戳的图像。在这种情况下，照片无法按拍摄顺序列出。为确保时间排序和字典排序使用相同的排序顺序，请设置环境变量 `LS_SAMESORT` 或使用 `-y` 选项。这使 `ls` 在对具有相同修改时间戳的文件排序时反转字典排序顺序。

**`-u`** 使用最后访问时间代替文件最后修改时间进行排序（`-t`）或打印（`-l`）。

**`-v`** 按自然顺序排序，使用 strverscmp(3) 而非 strcoll(3) 作为比较函数。例如，按字典顺序排序为 "bloem1"、"bloem10" 和 "bloem9" 的文件，将排序为 "bloem1"、"bloem9" 和 "bloem10"，这或许更符合预期。

**`-w`** 强制原始打印不可打印字符。这是输出不到终端时的默认行为。此选项未在 IEEE Std 1003.1-2001 ("POSIX.1") 中定义。

**`-x`** 与 `-C` 相同，但多列输出时条目按横向而非纵向排序。

**`-y`** 当设置了 `-t` 选项时，按与时间输出相同的顺序对字母输出进行排序。这与设置 `LS_SAMESORT` 的效果相同。详见 `-t` 选项的描述。此选项未在 IEEE Std 1003.1-2001 ("POSIX.1") 中定义。

**`-1`** （数字“一”。）强制输出为每行一条目。这是输出不到终端时的默认行为。

**`,`** （逗号）当设置了 `-l` 或 `-s` 选项时，使用 localeconv(3) 返回的非货币分隔符（通常是逗号或句点）按千位分组并分隔打印文件大小。如果未设置 locale，或 locale 没有非货币分隔符，此选项无效。此选项未在 IEEE Std 1003.1-2001 ("POSIX.1") 中定义。

`-1`、`-C`、`-x` 和 `-l` 选项都相互覆盖；最后指定的选项决定使用的格式。

`-c`、`-u` 和 `-U` 选项都相互覆盖；最后指定的选项决定使用的文件时间。

`-S`、`-t` 和 `-v` 选项相互覆盖；最后指定的选项决定使用的排序顺序。

`-B`、`-b`、`-w` 和 `-q` 选项都相互覆盖；最后指定的选项决定不可打印字符使用的格式。

`-H`、`-L` 和 `-P` 选项都相互覆盖（部分或完全）；它们按指定顺序应用。

默认情况下，`ls` 每行列出一个条目到标准输出；例外情况是输出到终端或指定了 `-C` 或 `-x` 选项时。

文件信息显示时，与 `-i`、`-s` 和 `-l` 选项关联的信息之间用一个或多个空格分隔。

### 长格式

如果给定 `-l` 选项，则对每个文件显示以下信息：文件模式、链接数、所有者名、组名、MAC 标签、文件字节数、缩写的月份、文件最后修改的月内日期、文件最后修改的小时、文件最后修改的分钟，以及路径名。

如果文件的修改时间在过去或未来超过 6 个月，且未指定 `-D` 或 `-T`，则显示最后修改的年份以代替小时和分钟字段。

如果所有者或组名不是已知的用户或组名，或给定 `-n` 选项，则显示数字 ID。

如果文件是字符特殊文件或块特殊文件，则文件设备号显示在大小字段中。如果文件是符号链接，则链接目标文件的路径名前会加上“`->`”。

目录内容的列表前面会有一个带标签的块总数，表示作为目录内容列出的文件在文件系统中使用的块数（根据其他选项，可能包括也可能不包括 `.` 和 `..` 以及其他以点开头的文件）。如果给定 `-h` 选项，则总大小以字节数显示。

默认块大小为 512 字节。块大小可通过 `-k` 选项或环境变量 `BLOCKSIZE` 设置。输出中的块数已向上取整，使字节数至少与相应文件系统块使用的数量相同（可能具有不同大小）。

`-l` 选项下打印的文件模式由条目类型和权限组成。条目类型字符描述文件的类型，如下：

**-** 普通文件。

**b** 块特殊文件。

**c** 字符特殊文件。

**d** 目录。

**l** 符号链接。

**p** FIFO。

**s** 套接字。

**w** Whiteout。

接下来的三个字段各为三个字符：所有者权限、组权限和其他权限。每个字段有三个字符位置：

* 如果是 **r**，文件可读；如果是 **-**，不可读。
* 如果是 **w**，文件可写；如果是 **-**，不可写。
* 以下最先适用的项：

**S** 如果在所有者权限中，文件不可执行且设置了 set-user-ID 模式。如果在组权限中，文件不可执行且设置了 set-group-ID 模式。

**s** 如果在所有者权限中，文件可执行且设置了 set-user-ID 模式。如果在组权限中，文件可执行且设置了 set-group-ID 模式。

**x** 文件可执行或目录可搜索。

**-** 文件既不可读、不可写、不可执行，也未设置 set-user-ID 或 set-group-ID 模式，也不是粘滞的。（参见下文。）

接下来两项仅适用于最后一组（其他权限）的第三个字符：

**T** 设置了粘滞位（模式 `1000`），但无执行或搜索权限。（参见 [chmod(1)](/man/man1/chmod.1.md) 或 [sticky(7)](https://github.com/FreeBSD-Ask/freebsd-man-sc/blob/main/man7/sticky.7.md)）

**t** 设置了粘滞位（模式 `1000`），且可搜索或可执行。（参见 [chmod(1)](/man/man1/chmod.1.md) 或 [sticky(7)](https://github.com/FreeBSD-Ask/freebsd-man-sc/blob/main/man7/sticky.7.md)）

下一个字段如果文件有 ACL 则包含加号（`+`）字符，如果没有则包含空格（ ）。`ls` 实用程序不显示实际的 ACL；使用 getfacl(1) 来执行此操作。

## 环境变量

以下环境变量影响 `ls` 的执行：

**`BLOCKSIZE`** 如果设置，其值（向上取整到 512 或向下取整到 512 的倍数）将作为 `-l` 和 `-s` 选项的块大小（字节）。详见“长格式”小节。

**`CLICOLOR`** 使用 ANSI 颜色序列区分文件类型。参见下文的 `LSCOLORS`。除了 `-F` 选项中提到的文件类型外，还显示一些额外的属性（如 setuid 位设置等）。着色依赖于具有适当 termcap(5) 能力的终端类型。默认的“`cons25`”控制台具有适当的能力，但要在 xterm(1)（`ports/x11/xterm`）中显示颜色，例如，必须将 `TERM` 变量设置为“`xterm-color`”。其他终端类型可能需要类似调整。如果输出未定向到终端，则静默禁用着色，除非定义了 `CLICOLOR_FORCE` 变量或将 `--color` 设置为“always”。

**`CLICOLOR_FORCE`** 如果输出未定向到终端，颜色序列通常被禁用。可通过设置此变量来覆盖。但 `TERM` 变量仍需引用支持颜色的终端，否则无法确定使用哪些颜色序列。

**`COLORTERM`** 参见上文 `CLICOLOR` 的描述。

**`COLUMNS`** 如果此变量包含表示十进制整数的字符串，则将其用作显示多文本列输出的列位置宽度。`ls` 实用程序根据提供的宽度计算显示多少路径名文本列。（参见 `-C` 和 `-x`。）

**`LANG`** 确定长 `-l` 格式输出中日和月顺序时使用的 locale。详见 [environ(7)](https://github.com/FreeBSD-Ask/freebsd-man-sc/blob/main/man7/environ.7.md)。

**`LSCOLORS`** 此变量的值描述了当通过 `CLICOLOR` 或 `COLORTERM` 启用颜色时，对每个属性使用什么颜色。此字符串由若干格式为 `f``b` 的对连接而成，其中 `f` 为前景色，`b` 为背景色。当背景色大写时，文本带下划线。

颜色标识符如下：

**a** 黑色

**b** 红色

**c** 绿色

**d** 棕色

**e** 蓝色

**f** 品红

**g** 青色

**h** 浅灰

**A** 加粗或带下划线的黑色，通常显示为深灰

**B** 加粗或带下划线的红色

**C** 加粗或带下划线的绿色

**D** 加粗或带下划线的棕色，通常显示为黄色

**E** 加粗或带下划线的蓝色

**F** 加粗或带下划线的品红

**G** 加粗或带下划线的青色

**H** 加粗或带下划线的浅灰；看起来像亮白

**x** 默认前景或背景

**X** 默认前景或背景，带下划线或加粗

注意，以上是标准 ANSI 颜色。实际显示可能因所用终端的颜色能力而异。

属性顺序如下：

1. 目录
2. 符号链接
3. 套接字
4. 管道
5. 可执行文件
6. 块特殊文件
7. 字符特殊文件
8. 设置了 setuid 位的可执行文件
9. 设置了 setgid 位的可执行文件
10. 对其他人可写的目录，带粘滞位
11. 对其他人可写的目录，不带粘滞位

默认值为 "exfxcxdxbxegedabagacad"，即常规目录为蓝色前景和默认背景，setuid 可执行文件为黑色前景和红色背景等。

**`LS_COLWIDTHS`** 如果设置此变量，则视为以冒号分隔的最小列宽列表。不合理和不足的宽度被忽略（因此零表示动态调整大小的列）。并非所有列都可更改宽度。各字段顺序为：inode、块数、链接数、用户名、组名、标志、文件大小、文件名。

**`LS_SAMESORT`** 如果设置此变量，`-t` 选项按与时间排序相同的方向对具有相同修改时间戳的文件名排序。详见 `-t` 选项的描述。

**`TERM`** `CLICOLOR` 和 `COLORTERM` 功能依赖于具有颜色能力的终端类型。

**`TZ`** 显示日期时使用的时区。详见 [environ(7)](https://github.com/FreeBSD-Ask/freebsd-man-sc/blob/main/man7/environ.7.md)。

## 退出状态

`ls` 实用程序成功时退出值为 0，发生错误时大于 0。

## 实例

以长格式列出当前工作目录的内容：

```sh
$ ls -l
```

除了以长格式列出当前工作目录的内容外，还显示 inode 编号、文件标志（参见 chflags(1)），并在每个文件名后附加表示其文件类型的符号：

```sh
$ ls -lioF
```

列出 **`/var/log`** 中的文件，对输出排序使最近修改的条目先打印：

```sh
$ ls -lt /var/log
```

## 兼容性

为了与 IEEE Std 1003.2 ("POSIX.2") 规范兼容，组字段现在自动包含在文件的长格式列表中。

## 参见

chflags(1), [chmod(1)](/man/man1/chmod.1.md), getfacl(1), [sort(1)](/man/man1/sort.1.md), xterm(1) (`ports/x11/xterm`), localeconv(3), strcoll(3), strftime(3), strmode(3), strverscmp(3), termcap(5), [maclabel(7)](https://github.com/FreeBSD-Ask/freebsd-man-sc/blob/main/man7/maclabel.7.md), [sticky(7)](https://github.com/FreeBSD-Ask/freebsd-man-sc/blob/main/man7/sticky.7.md), symlink(7), getfmac(8)

## 标准

除选项 `-g`、`-n` 和 `-o` 外，`ls` 实用程序符合 IEEE Std 1003.1-2001 ("POSIX.1") 和 IEEE Std 1003.1-2008 ("POSIX.1")。选项 `-B`、`-D`、`-G`、`-I`、`-T`、`-U`、`-W`、`-Z`、`-b`、`-h`、`-v`、`-w`、`-y`、`-,`、`--color` 和 `--group-directories=`（包括 `--group-directories-first`）是非标准扩展。

ACL 支持与 IEEE Std 1003.2c ("POSIX.2c") Draft 17（已撤销）兼容。

## 历史

`ls` 命令首次出现于 Version 1 AT\&T UNIX。

`-v` 选项在 FreeBSD 13.2 中添加。

## 缺陷

为保持向后兼容性，许多选项之间的关系相当复杂。

`-s` 选项描述中提到的例外可能是一个基于以下事实的特性：单列输出通常发送到终端以外的其他地方。这是否是设计缺陷尚有争议。

IEEE Std 1003.2 ("POSIX.2") 规定，使用 `-t` 选项排序时，对具有相同时间戳的文件采用相反的排序顺序。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://book.bsdcn.org/man/man1/ls.1.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.