View source for Ls

{{Short description|Command to list files and directories in Unix and Unix-like operating systems}}
{{Other uses|LS (disambiguation){{!}}LS}}
{{Lowercase|title=ls}}
{{Infobox software
| name                   = ls
| screenshot             = Ls --color=auto -ls linux.png
| caption                = Long file listing with <code>ls --color=auto -l</code> in Linux showing various modes, date formats, colors and appended indicators (executables and directories).
| author                 = coreutils: [[Richard Stallman]] and David MacKenzie
| developer              = Various [[open-source software|open-source]] and [[commercial software|commercial]] developers
| programming language   = [[C (programming language)|C]]
| operating system       = [[Multics]], [[Unix]], [[Unix-like]], [[Plan 9 from Bell Labs|Plan 9]], [[Inferno (operating system)|Inferno]], [[MSX-DOS]]
| genre                  = [[Command (computing)|Command]]
| license                = [[coreutils]]: [[GPLv3+]]<br />[[BusyBox]]: [[GNU General Public License|GPL-2.0-only]]<br />[[Toybox]]: [[BSD licenses|0BSD]]<br />Plan 9: [[MIT License]]
| website                =
}}
In [[computing]], '''<code>ls</code>''' is a [[Unix command|command]] to list [[computer file]]s and directories in [[Unix]] and [[Unix-like]] operating systems. It is specified by [[POSIX]] and the [[Single UNIX Specification]].
It is available in the [[Unified Extensible Firmware Interface|EFI shell]],<ref name="EFI-Shells-and-Scripting">{{cite web |title=EFI Shells and Scripting |url=http://software.intel.com/en-us/articles/efi-shells-and-scripting/ |url-status=deviated |archive-url=https://web.archive.org/web/20130927203229/http://software.intel.com/en-us/articles/efi-shells-and-scripting/ |archive-date=September 27, 2013 |access-date=2013-09-25 |publisher=[[Intel]]}}</ref> as a separate package for [[Microsoft Windows]] as part of the [[UnxUtils]] collection of [[Native (computing)|native]] [[Windows API|Win32]] [[porting|ports]] of common [[GNU]] Unix-like utilities,<ref>{{Cite web|url=http://unxutils.sourceforge.net/|title=Native Win32 ports of some GNU utilities|website=unxutils.sourceforge.net}}</ref>
or as part of [[ASCII Corporation|ASCII]]'s ''MSX-DOS2 Tools'' for [[MSX-DOS]] version 2.<ref>{{Cite web|url=https://archive.org/details/MSXDOS2TOOLS|title=MSX-DOS2 Tools User's Manual - MSX-DOS2 TOOLS ユーザーズマニュアル|date=April 1, 1993|via=Internet Archive}}</ref>
The [[numerical analysis|numerical computing]] environments [[MATLAB]] and [[GNU Octave]] include an <code>ls</code>
function with similar functionality.<ref>{{Cite web|url=https://www.mathworks.com/help/matlab/ref/ls.html|title = List folder contents - MATLAB ls}}</ref><ref>{{Cite web |title=Function Reference: Ls |url=https://octave.sourceforge.io/octave/function/ls.html |website=Octave Forge}}</ref>
In other environments, such as [[DOS]], [[OS/2]], and [[Microsoft Windows]], similar functionality is provided by the <code>[[dir (command)|dir]]</code> command.
== History ==
An <code>ls</code> utility appeared in the first version of [[AT&T Corporation|AT&T]] [[Unix|UNIX]], the name inherited from a similar command in [[Multics]] also named 'ls', short for the word "list".<ref>{{Cite web |date=14 February 1985 |title=Multics manual page for ls or list command |url=https://web.mit.edu/multics-history/source/Multics/doc/info_segments/list.info}}</ref><ref>{{cite web |url=https://tldp.org/LDP/LG/issue48/fischer.html |title=A Brief History of the 'ls' command |first=Eric |last=Fischer |website=[[The Linux Documentation Project]]}}</ref><ref>{{cite web | url = http://bitsavers.org/pdf/honeywell/large_systems/multics/AG92-03A_multicsCmds_Feb80.pdf | title = Multics programmer's manual - Commands and active functions | page = 397 }}</ref> {{code|ls}} is part of the [[X/Open]] Portability Guide since issue 2 of 1987. It was inherited into the first version of POSIX.1 and the [[Single Unix Specification]].<ref>{{man|cu|ls|SUS}}</ref>
== Behavior ==
[[Unix]] and [[Unix-like]] operating systems maintain the idea of a [[working directory]]. When invoked without [[Command-line argument|argument]]s, <code>ls</code> lists the files in the working directory. If a directory is specified as an argument, the files in that directory are listed; if a file is specified, that file is listed. Multiple directories and files may be specified.
In many Unix-like systems, names starting with a [[Dot (character)|dot]] (<code>.</code>) are [[Hidden file and hidden directory#Unix and Unix-like environments|hidden]]. Examples are <code>.</code>, which refers to the working directory, and <code>..</code>, which refers to its parent directory.  Hidden names are not shown by default. With <code>-a</code>, all names, including all hidden names, are shown. Using <code>-A</code> shows all names, including hidden names, except for <code>.</code> and <code>..</code>.  File names specified explicitly (for example <code>ls .secret</code>) are always listed.
Without options, <code>ls</code> displays names only.
The different implementations have different options, but common options include:
* <code>-l</code> Long format, displaying [[Unix file types]], permissions, number of [[hard link]]s, owner, group, size, last-modified date-time and name. If the modified date is older than 6 months, the time is replaced with the year. Some implementations add additional flags to permissions. The file type can be one of 8 characters: <code>-</code>, regular file; <code>d</code>, directory; <code>l</code>, [[Symbolic link|symbolic (soft) link]]; <code>n</code>, [[Network filesystem|network files]]; <code>s</code>, [[Network socket|socket]]; <code>p</code>, [[named pipe]] (FIFO); <code>c</code>, [[Device file|character special file]]; <code>b</code>, [[Device file|block special file]].
* <code>-h</code> Output sizes in human readable format (e.g., 1K ([[kilobyte]]s), 234M ([[megabyte]]s), 2G ([[gigabyte]]s)). This option is not part of the POSIX standard, although implemented in several systems, e.g., GNU coreutils in 1997,<ref>{{cite web |url=http://git.savannah.gnu.org/cgit/coreutils.git/commit/src/ls.c?id=b76a4533046163978f7517f9ea6d3307bfa0a98a |title=(decode_switches): -h and -H override output units. |publisher=coreutils.git |date=1997-12-31 }}</ref> FreeBSD 4.5 in 2002,<ref>{{cite web |url=https://svnweb.freebsd.org/base?view=revision&revision=88591 |title=[base] Log of /stable/10/bin/ls/ls.c |date=2001-12-28}}</ref> and Solaris 9 in 2002.<ref>{{citation |url=http://docs.oracle.com/cd/E19683-01/806-5202/6je7shk5c/index.html |title=What's New in the Solaris 9 Operating Environment |publisher=Sun Microsystems |year=2002}}</ref>
Additional options controlling how items are displayed include:
* <code>-R</code> Recursively list items in subdirectories.
* <code>-t</code> Sort the list by modification time (default sort is alphabetically).
* <code>-u</code> Sort the list by last access time.
* <code>-c</code> Sort the list by last attribute (status) change time.
* <code>-r</code> Reverse the order, for example most recent time last.
* <code>--full-time</code> Show times down to the second and millisecond instead of just the minute.
* <code>-1</code> One entry per line.
* <code>-m</code> Stream format; list items across the page, separated by commas.
* <code>-g</code> Include group but not owner.
* <code>-o</code> Include owner but not group (when combined with <code>-g</code> both group and owner are suppressed).
* <code>-d</code> Show information about a directory or symbolic link, rather than the contents of a directory or the link's target.
* <code>-F</code> Append a "/" to directory names and a "*" to executable files.
It may be possible to highlight different types of items with different colors. This is an area where implementations differ:
* [[GNU]] <code>ls</code> uses the <code>--color</code> option;<ref>{{Cite web |title=General output formatting (GNU Coreutils 9.1) |url=https://www.gnu.org/software/coreutils/manual/html_node/General-output-formatting.html |access-date=2023-01-07 |website=www.gnu.org}}</ref> it checks the Unix file type, the file permissions and the file extension and uses its own database to control colors maintained using [[dircolors]].
* [[FreeBSD]] <code>ls</code> uses the <code>-G</code> option; it checks only the Unix file type and file permissions and uses the [[termcap]] database<ref>{{cite web |url=http://www.freebsd.org/cgi/man.cgi?query=ls |title=FreeBSD Man Pages &mdash; ls |access-date=June 23, 2013 }}</ref>
When the option to use color to indicate item types is selected, the output might look like:
-rw-r--r--    1 tsmitt nregion   26650 Dec 20 11:16 <span style="color:dodgerblue                   ">audio.ogg</span>
brw-r--r--    1 tsmitt nregion      64 Jan 27 05:52 <span style="color:chocolate                 ">bd-block-device</span>
crw-r--r--    1 tsmitt nregion     255 Jan 26 13:57 <span style="color:chocolate                 ">cd-character-device</span>
-rw-r--r--    1 tsmitt nregion     290 Jan 26 14:08 <span style="color:magenta                ">image.png</span>
drwxrwxr-x    2 tsmitt nregion      48 Jan 26 11:28 <span style="color:blue                   ">di-directory</span>
-rwxrwxr-x    1 tsmitt nregion      29 Jan 26 14:03 <span style="color:green                   ">ex-executable</span>
-rw-r--r--    1 tsmitt nregion       0 Dec 20 09:39 <span style="color:dimgray                ">fi-regular-file</span>
lrwxrwxrwx    1 tsmitt nregion       3 Jan 26 11:44 <span style="color:dodgerblue                   ">ln-soft-link</span> -> <span style="color:blue">dir</span>
lrwxrwxrwx    1 tsmitt nregion      15 Dec 20 10:57 <span style="color:lightcoral             ">or-orphan-link</span> -> <span style="color:white;background:lightcoral">mi-missing-link</span>
drwxr-xrwx    2 tsmitt nregion    4096 Dec 20 10:58 <span style="color:blue;background:lime   ">ow-other-writeable-dir</span>
prw-r--r--    1 tsmitt nregion       0 Jan 26 11:50 <span style="color:darkgoldenrod                ">pi-pipe</span>
-rwxr-sr-x    1 tsmitt nregion       0 Dec 20 11:05 <span style="color:black;background:yellow">sg-setgid</span>
srw-rw-rw-    1 tsmitt nregion       0 Jan 26 12:00 <span style="color:magenta                ">so-socket</span>
drwxr-xr-t    2 tsmitt nregion    4096 Dec 20 10:58 <span style="color:white;background:blue  ">st-sticky-dir</span>
-rwsr-xr-x    1 tsmitt nregion       0 Dec 20 11:09 <span style="color:white;background:red   ">su-setuid</span>
-rw-r--r--    1 tsmitt nregion   10240 Dec 20 11:12 <span style="color:red                    ">compressed.gz</span>
drwxrwxrwt    2 tsmitt nregion    4096 Dec 20 11:10 <span style="color:black;background:lime  ">tw-sticky-other-writeable-dir</span>
== Sample usage ==
The following example demonstrates the output of the command:
<syntaxhighlight lang="console">
$ ls -l
drwxr--r--   1 fjones editors     4096 Mar  2 12:52  drafts
-rw-r--r--   3 fjones editors    30405 Mar  2 12:52  edition-32
-r-xr-xr-x   1 fjones bookkeepers 8460 Jan 16  2022  edit.sh
</syntaxhighlight>
Each line shows the <code>d</code> (directory) or <code>-</code> (file) indicator, [[File system permissions#Notation of traditional Unix permissions|Unix file permission notation]], number of [[hard link]]s (1 or 3), the file's owner, the file's group, the file size, the modification date/time, and the file name. In the working directory, the owner <code>fjones</code> has a directory named <code>drafts</code>, a regular file named <code>edition-32</code>, and an executable named <code>edit.sh</code> which is "old", i.e. modified more than 6 months ago as indicated by the display of the year.<syntaxhighlight lang="console">
┌─────────── file (not a directory)
|┌─────────── read-write (no execution) permissions for the owner
|│  ┌───────── read-only permissions for the group
|│  │  ┌─────── read-only permissions for others
|│  │  │     ┌── number of hard links
|│  │  │     │   ┌── owner
|│  │  │     │   │     ┌── user group
|│  │  │     │   │     │          ┌── file size in bytes
|│  │  │     │   │     │          │    ┌── last modified on
|│  │  │     │   │     │          │    │                ┌── filename
-rw-r--r--   3 fjones editors    30405 Mar  2 12:52  edition-32
</syntaxhighlight>
== See also ==
* [[stat (Unix)]]
* [[chown]]
* [[chgrp]]
* [[du (Unix)]]
* [[mdls]]
* [[User identifier (Unix)]]
* [[Group identifier (Unix)]]
* [[List of Unix commands]]
* [[Unix directory structure]]
== References ==
{{Reflist}}
== External links ==
{{Wikibooks|Guide to Unix|Commands}}
* {{man|cu|ls}}
* {{man|1|ls|FreeBSD}}
* {{man|1|ls|NetBSD}}
* {{man|1|ls|OpenBSD}}
* {{man|1|ls|Solaris}}
* {{man|1|ls|Linux}}
* {{man|1|ls|Plan 9}}
* {{man|1|ls|Inferno}}
* [http://ftp.gnu.org/pub/gnu/coreutils/ GNU <code>ls</code> source code (as part of coreutils)]
* [http://wiki.linuxquestions.org/wiki/Ls <code>ls</code>] at the LinuxQuestions.org wiki
{{Unix commands}}
{{Plan 9 commands}}
{{Core Utilities commands}}
[[Category:Multics commands]]
[[Category:Standard Unix programs]]
[[Category:Unix SUS2008 utilities]]
[[Category:Plan 9 commands]]
[[Category:Inferno (operating system) commands]]
[[Category:IBM i Qshell commands]]