3/6/2017 ls.

1pLinuxmanualpage

man7.org>Linux>manpages Linux/UNIXsystemprogrammingtraining

PROLOG|NAME|SYNOPSIS|DESCRIPTION|OPTIONS|OPERANDS|STDIN|
INPUTFILES|ENVIRONMENTVARIABLES|ASYNCHRONOUSEVENTS|STDOUT|
STDERR|OUTPUTFILES|EXTENDEDDESCRIPTION|EXITSTATUS|
Searchonlinepages
CONSEQUENCESOFERRORS|APPLICATIONUSAGE|EXAMPLES|RATIONALE|
FUTUREDIRECTIONS|SEEALSO|COPYRIGHT

LS(1P)POSIXProgrammer'sManualLS(1P)

PROLOGtop

ThismanualpageispartofthePOSIXProgrammer'sManual.TheLinux
implementationofthisinterfacemaydiffer(consultthe
correspondingLinuxmanualpagefordetailsofLinuxbehavior),or
theinterfacemaynotbeimplementedonLinux.

NAMEtop

lslistdirectorycontents

SYNOPSIStop

ls[ikqrs][glno][A|a][C|m|x|1]\
[F|p][H|L][R|d][S|f|t][c|u][file...]

DESCRIPTIONtop

Foreachoperandthatnamesafileofatypeotherthandirectoryor
symboliclinktoadirectory,lsshallwritethenameofthefileas
wellasanyrequested,associatedinformation.Foreachoperandthat
namesafileoftypedirectory,lsshallwritethenamesoffiles
containedwithinthedirectoryaswellasanyrequested,associated
information.Filenamesbeginningwitha<period>('.')andany
associatedinformationshallnotbewrittenoutunlessexplicitly
referenced,theAoraoptionissupplied,oranimplementation
definedconditioncausesthemtobewritten.Ifoneormoreofthe
d,F,orloptionsarespecified,andneithertheHnortheL
optionisspecified,foreachoperandthatnamesafileoftype
symboliclinktoadirectory,lsshallwritethenameofthefileas
wellasanyrequested,associatedinformation.Ifnoneofthed,F,
orloptionsarespecified,ortheHorLoptionsarespecified,
foreachoperandthatnamesafileoftypesymboliclinktoa
directory,lsshallwritethenamesoffilescontainedwithinthe
directoryaswellasanyrequested,associatedinformation.Ineach
casewherethenamesoffilescontainedwithinadirectoryare
written,ifthedirectorycontainsanysymboliclinksthenlsshall
evaluatethefileinformationandfiletypetobethoseofthe
symboliclinkitself,unlesstheLoptionisspecified.
http://man7.org/linux/manpages/man1/ls.1p.html 1/15
3/6/2017 ls.1pLinuxmanualpage

symboliclinkitself,unlesstheLoptionisspecified.

Ifnooperandsarespecified,lsshallbehaveasifasingleoperand
ofdot('.')hadbeenspecified.Ifmorethanoneoperandis
specified,lsshallwritenondirectoryoperandsfirst;itshallsort
directoryandnondirectoryoperandsseparatelyaccordingtothe
collatingsequenceinthecurrentlocale.

Thelsutilityshalldetectinfiniteloops;thatis,enteringa
previouslyvisiteddirectorythatisanancestorofthelastfile
encountered.Whenitdetectsaninfiniteloop,lsshallwritea
diagnosticmessagetostandarderrorandshalleitherrecoverits
positioninthehierarchyorterminate.

OPTIONStop

ThelsutilityshallconformtotheBaseDefinitionsvolumeof
POSIX.12008,Section12.2,UtilitySyntaxGuidelines.

Thefollowingoptionsshallbesupported:

AWriteoutalldirectoryentries,includingthosewhose
namesbeginwitha<period>('.')butexcludingthe
entriesdotanddotdot(iftheyexist).

CWritemultitextcolumnoutputwithentriessorteddownthe
columns,accordingtothecollatingsequence.Thenumberof
textcolumnsandthecolumnseparatorcharactersare
unspecified,butshouldbeadaptedtothenatureofthe
outputdevice.Thisoptiondisableslongformatoutput.

FDonotfollowsymboliclinksnamedasoperandsunlessthe
HorLoptionsarespecified.Writea<slash>('/')
immediatelyaftereachpathnamethatisadirectory,an
<asterisk>('*')aftereachthatisexecutable,a
<verticalline>('|')aftereachthatisaFIFO,andanat
sign('@')aftereachthatisasymboliclink.Forother
filetypes,othersymbolsmaybewritten.

HEvaluatethefileinformationandfiletypeforsymbolic
linksspecifiedonthecommandlinetobethoseofthefile
referencedbythelink,andnotthelinkitself;however,
lsshallwritethenameofthelinkitselfandnotthefile
referencedbythelink.

LEvaluatethefileinformationandfiletypeforall
symboliclinks(whethernamedonthecommandlineor
encounteredinafilehierarchy)tobethoseofthefile
referencedbythelink,andnotthelinkitself;however,
lsshallwritethenameofthelinkitselfandnotthefile

referencedbythelink.WhenLisusedwithl,writethe
http://man7.org/linux/manpages/man1/ls.1p.html 2/15
3/6/2017 ls.1pLinuxmanualpage
referencedbythelink.WhenLisusedwithl,writethe
contentsofsymboliclinksinthelongformat(seethe
STDOUTsection).

RRecursivelylistsubdirectoriesencountered.Whena
symboliclinktoadirectoryisencountered,thedirectory
shallnotberecursivelylistedunlesstheLoptionis
specified.TheuseofRwithdorfproduces
unspecifiedresults.

SSortwiththeprimarykeybeingfilesize(indecreasing
order)andthesecondarykeybeingfilenameinthe
collatingsequence(inincreasingorder).

aWriteoutalldirectoryentries,includingthosewhose
namesbeginwitha<period>('.').

cUsetimeoflastmodificationofthefilestatus
information(seetheBaseDefinitionsvolumeof
POSIX.12008,sys_stat.h(0p))insteadoflastmodification
ofthefileitselfforsorting(t)orwriting(l).

dDonotfollowsymboliclinksnamedasoperandsunlessthe
HorLoptionsarespecified.Donottreatdirectories
differentlythanothertypesoffiles.Theuseofdwith
Rorfproducesunspecifiedresults.

fListtheentriesindirectoryoperandsintheorderthey
appearinthedirectory.Thebehaviorfornondirectory
operandsisunspecified.Thisoptionshallturnona.
Whenfisspecified,anyoccurrencesofther,S,andt
optionsshallbeignoredandanyoccurrencesoftheA,g,
l,n,o,andsoptionsmaybeignored.Theuseoff
withRordproducesunspecifiedresults.

gTurnonthel(ell)option,butdisablewritingthefile's
ownernameornumber.DisabletheC,m,andxoptions.

iForeachfile,writethefile'sfileserialnumber(see
stat()intheSystemInterfacesvolumeofPOSIX.12008).

kSettheblocksizeforthesoptionandtheperdirectory
blockcountwrittenforthel,n,s,g,andooptions
(seetheSTDOUTsection)to1024bytes.

l(Theletterell.)Donotfollowsymboliclinksnamedas
operandsunlesstheHorLoptionsarespecified.Write
outinlongformat(seetheSTDOUTsection).Disablethe
C,m,andxoptions.

mStreamoutputformat;listpathnamesacrossthepage,
separatedbya<comma>characterfollowedbya<space>
http://man7.org/linux/manpages/man1/ls.1p.html 3/15
3/6/2017 ls.1pLinuxmanualpage
separatedbya<comma>characterfollowedbya<space>
character.Usea<newline>characterasthelistterminator
andaftertheseparatorsequencewhenthereisnotroomon
alineforthenextlistentry.Thisoptiondisableslong
formatoutput.

nTurnonthel(ell)option,butwhenwritingthefile's
ownerorgroup,writethefile'snumericUIDorGIDrather
thantheuserorgroupname,respectively.DisabletheC,
m,andxoptions.

oTurnonthel(ell)option,butdisablewritingthefile's
groupnameornumber.DisabletheC,m,andxoptions.

pWritea<slash>('/')aftereachfilenameifthatfileisa
directory.

qForceeachinstanceofnonprintablefilenamecharacters
and<tab>characterstobewrittenasthe<questionmark>
('?')character.Implementationsmayprovidethisoption
bydefaultiftheoutputistoaterminaldevice.

rReversetheorderofthesorttogetreversecollating
sequenceoldestfirst,orsmallestfilesizefirst
dependingontheotheroptionsgiven.

sIndicatethetotalnumberoffilesystemblocksconsumedby
eachfiledisplayed.Ifthekoptionisalsospecified,
theblocksizeshallbe1024bytes;otherwise,theblock
sizeisimplementationdefined.

tSortwiththeprimarykeybeingtimemodified(most
recentlymodifiedfirst)andthesecondarykeybeing
filenameinthecollatingsequence.Forasymboliclink,
thetimeusedasthesortkeyisthatofthesymboliclink
itself,unlesslsisevaluatingitsfileinformationtobe
thatofthefilereferencedbythelink(seetheHandL
options).

uUsetimeoflastaccess(seetheBaseDefinitionsvolumeof
POSIX.12008,sys_stat.h(0p))insteadoflastmodification
ofthefileforsorting(t)orwriting(l).

xThesameasC,exceptthatthemultitextcolumnoutputis
producedwithentriessortedacross,ratherthandown,the
columns.Thisoptiondisableslongformatoutput.

1(Thenumericdigitone.)Forceoutputtobeoneentryper
line.Thisoptiondoesnotdisablelongformatoutput.
(Longformatoutputisenabledbyg,l(ell),n,ando;
anddisabledbyC,m,andx.)

http://man7.org/linux/manpages/man1/ls.1p.html 4/15
3/6/2017 ls.1pLinuxmanualpage

Ifanoptionthatenableslongformatoutput(g,l(ell),n,and
oisgivenwithanoptionthatdisableslongformatoutput(C,m,
andx),thisshallnotbeconsideredanerror.Thelastofthese
optionsspecifiedshalldeterminewhetherlongformatoutputis
written.

IfR,d,orfarespecified,theresultsofspecifyingthese
mutuallyexclusiveoptionsarespecifiedbythedescriptionsofthese
optionsabove.Ifmorethanoneofanyoftheotheroptionsshownin
theSYNOPSISsectioninmutuallyexclusivesetsaregiven,thisshall
notbeconsideredanerror;thelastoptionspecifiedineachset
shalldeterminetheoutput.

Notethatiftisspecified,canduarenotonlymutually
exclusivewitheachother,theyarealsomutuallyexclusivewithS
whendeterminingsortorder.ButevenifSisspecifiedafterall
occurrencesofc,t,andu,thelastuseofcorudetermines
thetimestampprintedwhenproducinglongformatoutput.

OPERANDStop

Thefollowingoperandshallbesupported:

fileApathnameofafiletobewritten.Ifthefilespecified
isnotfound,adiagnosticmessageshallbeoutputon
standarderror.

STDINtop

Notused.

INPUTFILEStop

None.

ENVIRONMENTVARIABLEStop

Thefollowingenvironmentvariablesshallaffecttheexecutionofls:

COLUMNSDeterminetheuser'spreferredcolumnpositionwidthfor
writingmultipletextcolumnoutput.Ifthisvariable
containsastringrepresentingadecimalinteger,thels
utilityshallcalculatehowmanypathnametextcolumnsto
write(seeC)basedonthewidthprovided.IfCOLUMNSis
notsetorinvalid,animplementationdefinednumberof
columnpositionsshallbeassumed,basedonthe
implementation'sknowledgeoftheoutputdevice.Thecolumn
widthchosentowritethenamesoffilesinanygiven
http://man7.org/linux/manpages/man1/ls.1p.html 5/15
3/6/2017 ls.1pLinuxmanualpage
widthchosentowritethenamesoffilesinanygiven
directoryshallbeconstant.Filenamesshallnotbe
truncatedtofitintothemultipletextcolumnoutput.

LANGProvideadefaultvaluefortheinternationalization
variablesthatareunsetornull.(SeetheBaseDefinitions
volumeofPOSIX.12008,Section8.2,Internationalization
Variablesfortheprecedenceofinternationalization
variablesusedtodeterminethevaluesoflocale
categories.)

LC_ALLIfsettoanonemptystringvalue,overridethevaluesof
alltheotherinternationalizationvariables.

LC_COLLATE
Determinethelocaleforcharactercollationinformationin
determiningthepathnamecollationsequence.

LC_CTYPEDeterminethelocalefortheinterpretationofsequencesof
bytesoftextdataascharacters(forexample,singlebyte
asopposedtomultibytecharactersinarguments)andwhich
charactersaredefinedasprintable(characterclass
print).

LC_MESSAGES
Determinethelocalethatshouldbeusedtoaffectthe
formatandcontentsofdiagnosticmessageswrittento
standarderror.

LC_TIMEDeterminetheformatandcontentsfordateandtimestrings
writtenbyls.

NLSPATHDeterminethelocationofmessagecatalogsforthe
processingofLC_MESSAGES.

TZDeterminethetimezonefordateandtimestringswrittenby
ls.IfTZisunsetornull,anunspecifieddefault
timezoneshallbeused.

ASYNCHRONOUSEVENTStop

Default.

STDOUTtop

Thedefaultformatshallbetolistoneentryperlinetostandard
output;theexceptionsaretoterminalsorwhenoneoftheC,m,or
xoptionsisspecified.Iftheoutputistoaterminal,theformat
isimplementationdefined.

http://man7.org/linux/manpages/man1/ls.1p.html 6/15
3/6/2017 ls.1pLinuxmanualpage

Whenmisspecified,theformatusedforthelastelementofthe
listshallbe:

"%s\n",<filename>

Theformatusedforeachotherelementofthelistshallbe:

"%s,%s",<filename>,<separator>

where,ifthereisnotroomforthenextelementofthelisttofit
withinthecurrentlinelength,<separator>isastringcontainingan
optional<space>characterandamandatory<newline>character;
otherwiseitisasingle<space>character.

Iftheioptionisspecified,thefile'sfileserialnumber(seethe
BaseDefinitionsvolumeofPOSIX.12008,sys_stat.h(0p))shallbe
writteninthefollowingformatbeforeanyotheroutputforthe
correspondingentry:

%u",<fileserialnumber>

Iftheloptionisspecified,thefollowinginformationshallbe
writtenforfilesotherthancharacterspecialandblockspecial
files:

"%s%u%s%s%u%s%s\n",<filemode>,<numberoflinks>,
<ownername>,<groupname>,<size>,<dateandtime>,
<pathname>

Iftheloptionisspecified,thefollowinginformationshallbe
writtenforcharacterspecialandblockspecialfiles:

"%s%u%s%s%s%s%s\n",<filemode>,<numberoflinks>,
<ownername>,<groupname>,<deviceinfo>,<dateandtime>,
<pathname>

InbothcasesifthefileisasymboliclinkandtheLoptionis
alsospecified,thisinformationshallbeforthefileresolvedfrom
thesymboliclink,exceptthatthe<pathname>fieldshallcontainthe
pathnameofthesymboliclinkitself.Ifthefileisasymboliclink
andtheLoptionisnotspecified,thisinformationshallbeabout
thelinkitselfandthe<pathname>fieldshallbeoftheform:

"%s>%s",<pathnameoflink>,<contentsoflink>

Then,g,andooptionsusethesameformatasl,butwith
omitteditemsandtheirassociated<blank>characters.Seethe
OPTIONSsection.

Inboththeprecedinglforms,if<ownername>or<groupname>
cannotbedetermined,orifnisgiven,theyshallbereplacedwith
http://man7.org/linux/manpages/man1/ls.1p.html 7/15
3/6/2017 ls.1pLinuxmanualpage
cannotbedetermined,orifnisgiven,theyshallbereplacedwith
theirassociatednumericvaluesusingtheformat%u.

The<size>fieldshallcontainthevaluethatwouldbereturnedfor
thefileinthest_sizefieldofstructstat(seetheBase
DefinitionsvolumeofPOSIX.12008,sys_stat.h(0p)).Notethatfor
somefiletypesthisvalueisunspecified.

The<deviceinfo>fieldshallcontainimplementationdefined
informationassociatedwiththedeviceinquestion.

The<dateandtime>fieldshallcontaintheappropriatedateand
timestampofwhenthefilewaslastmodified.InthePOSIXlocale,
thefieldshallbetheequivalentoftheoutputofthefollowingdate
command:

date"+%b%e%H:%M"

ifthefilehasbeenmodifiedinthelastsixmonths,or:

date"+%b%e%Y"

(wheretwo<space>charactersareusedbetween%eand%Y)ifthefile
hasnotbeenmodifiedinthelastsixmonthsorifthemodification
dateisinthefuture,exceptthat,inbothcases,thefinal
<newline>producedbydateshallnotbeincludedandtheoutputshall
beasifthedatecommandwereexecutedatthetimeofthelast
modificationdateofthefileratherthanthecurrenttime.Whenthe
LC_TIMElocalecategoryisnotsettothePOSIXlocale,adifferent
formatandorderofpresentationofthisfieldmaybeused.

Ifthepathnamewasspecifiedasafileoperand,itshallbewritten
asspecified.

Thefilemodewrittenunderthel,n,g,andooptionsshall
consistofthefollowingformat:

"%c%s%s%s%s",<entrytype>,<ownerpermissions>,
<grouppermissions>,<otherpermissions>,
<optionalalternateaccessmethodflag>

The<optionalalternateaccessmethodflag>shallbetheemptystring
ifthereisnoalternateoradditionalaccesscontrolmethod
associatedwiththefile;otherwise,itshallbeastringcontaining
asingleprintablecharacterthatisnota<blank>.

The<entrytype>charactershalldescribethetypeoffile,as
follows:

dDirectory.

bBlockspecialfile.
http://man7.org/linux/manpages/man1/ls.1p.html 8/15
3/6/2017 ls.1pLinuxmanualpage
bBlockspecialfile.

cCharacterspecialfile.

l(ell)Symboliclink.

pFIFO.

Regularfile.

Implementationsmayaddothercharacterstothislisttorepresent
otherimplementationdefinedfiletypes.

Thenextthreefieldsshallbethreecharacterseach:

<ownerpermissions>
Permissionsforthefileownerclass(seetheBaseDefinitions
volumeofPOSIX.12008,Section4.4,FileAccessPermissions).

<grouppermissions>
Permissionsforthefilegroupclass.

<otherpermissions>
Permissionsforthefileotherclass.

Eachfieldshallhavethreecharacterpositions:

1.If'r',thefileisreadable;if'',thefileisnotreadable.

2.If'w',thefileiswritable;if'',thefileisnotwritable.

3.Thefirstofthefollowingthatapplies:

SIfin<ownerpermissions>,thefileisnotexecutableand
setuserIDmodeisset.Ifin<grouppermissions>,the
fileisnotexecutableandsetgroupIDmodeisset.

sIfin<ownerpermissions>,thefileisexecutableandset
userIDmodeisset.Ifin<grouppermissions>,thefileis
executableandsetgroupIDmodeisset.

TIfin<otherpermissions>andthefileisadirectory,
searchpermissionisnotgrantedtoothers,andthe
restricteddeletionflagisset.

tIfin<otherpermissions>andthefileisadirectory,
searchpermissionisgrantedtoothers,andtherestricted
deletionflagisset.

xThefileisexecutableorthedirectoryissearchable.

Noneoftheattributesof'S','s','T','t',or'x'
http://man7.org/linux/manpages/man1/ls.1p.html 9/15
3/6/2017 ls.1pLinuxmanualpage
Noneoftheattributesof'S','s','T','t',or'x'
applies.

Implementationsmayaddothercharacterstothislistforthe
thirdcharacterposition.Suchadditionsshall,however,be
writteninlowercaseifthefileisexecutableorsearchable,and
inuppercaseifitisnot.

Ifanyofthel,n,s,g,orooptionsisspecified,eachlist
offileswithinthedirectoryshallbeprecededbyastatusline
indicatingthenumberoffilesystemblocksoccupiedbyfilesinthe
directoryin512byteunitsifthekoptionisnotspecified,or
1024byteunitsifthekoptionisspecified,roundeduptothenext
integralnumberofunits,ifnecessary.InthePOSIXlocale,the
formatshallbe:

"total%u\n",<numberofunitsinthedirectory>

Ifmorethanonedirectory,oracombinationofnondirectoryfiles
anddirectoriesarewritten,eitherasaresultofspecifying
multipleoperands,ortheRoption,eachlistoffileswithina
directoryshallbeprecededby:

"\n%s:\n",<directoryname>

Ifthisstringisthefirstthingtobewritten,thefirst<newline>
shallnotbewritten.Thisoutputshallprecedethenumberofunits
inthedirectory.

Ifthesoptionisgiven,eachfileshallbewrittenwiththenumber
ofblocksusedbythefile.AlongwithC,1,m,orx,thenumber
anda<space>shallprecedethefilename;withl,n,g,oro,
theyshallprecedeeachlinedescribingafile.

STDERRtop

Thestandarderrorshallbeusedonlyfordiagnosticmessages.

OUTPUTFILEStop

None.

EXTENDEDDESCRIPTIONtop

None.

EXITSTATUStop

Thefollowingexitvaluesshallbereturned:
http://man7.org/linux/manpages/man1/ls.1p.html 10/15
3/6/2017 ls.1pLinuxmanualpage

0Successfulcompletion.

>0Anerroroccurred.

CONSEQUENCESOFERRORStop

Default.

Thefollowingsectionsareinformative.

APPLICATIONUSAGEtop

Manyimplementationsusethe<equalssign>('=')todenotesockets
boundtothefilesystemfortheFoption.Similarly,many
historicalimplementationsusethe's'charactertodenotesocketsas
theentrytypecharactersfortheloption.

Itisdifficultforanapplicationtouseeverypartofthefile
modesfieldoflslinaportablemanner.Certainfiletypesand
executablebitsarenotguaranteedtobeexactlyasshown,as
implementationsmayhaveextensions.Applicationscanusethisfield
topassdirectlytoauserprintoutorprompt,butactionsbasedon
itscontentsshouldgenerallybedeferred,instead,tothetest
utility.

Theoutputofls(withthelandrelatedoptions)contains
informationthatlogicallycouldbeusedbyutilitiessuchaschmod
andtouchtorestorefilestoaknownstate.However,this
informationispresentedinaformatthatcannotbeuseddirectlyby
thoseutilitiesorbeeasilytranslatedintoaformatthatcanbe
used.Acharacterhasbeenaddedtotheendofthepermissionsstring
sothatapplicationsatleasthaveanindicationthattheymaybe
workinginanareatheydonotunderstandinsteadofassumingthat
theycantranslatethepermissionsstringintosomethingthatcanbe
used.Futureversionsorrelateddocumentsmaydefineoneormore
specificcharacterstobeusedbasedondifferentstandardadditional
oralternativeaccesscontrolmechanisms.

Aswithmanyoftheutilitiesthatdealwithfilenames,theoutputof
lsformultiplefilesorinoneofthelonglistingformatsmustbe
usedcarefullyonsystemswherefilenamescancontainembeddedwhite
space.Systemsandsystemadministratorsshouldinstitutepolicies
andusertrainingtolimittheuseofsuchfilenames.

Thenumberofdiskblocksoccupiedbythefilethatitreportsvaries
dependingonunderlyingfilesystemtype,blocksizeunitsreported,
andthemethodofcalculatingthenumberofblocks.Onsomefile

systemtypes,thenumberistheactualnumberofblocksoccupiedby
thefile(countingindirectblocksandignoringholesinthefile);
http://man7.org/linux/manpages/man1/ls.1p.html 11/15
3/6/2017 ls.1pLinuxmanualpage
thefile(countingindirectblocksandignoringholesinthefile);
onothersitiscalculatedbasedonthefilesize(usuallymakingan
allowanceforindirectblocks,butignoringholes).

EXAMPLEStop

Anexampleofasmalldirectorytreebeingfullylistedwithls
laRFainthePOSIXlocale:

total11
drwxrxrx3foxprog64Jul412:07./
drwxrwxrwx4foxprog3264Jul412:09../
drwxrxrx2foxprog48Jul412:07b/
rwxrr1foxprog572Jul412:07foo*

a/b:
total4
drwxrxrx2foxprog48Jul412:07./
drwxrxrx3foxprog64Jul412:07../
rwrr1foxprog700Jul412:07bar

RATIONALEtop

Somehistoricalimplementationsofthelsutilityshowallentriesin
adirectoryexceptdotanddotdotwhenasuperuserinvokesls
withoutspecifyingtheaoption.When``normal''usersinvokels
withoutspecifyinga,theyshouldnotseeinformationaboutany
fileswithnamesbeginningwitha<period>unlesstheywerenamedas
fileoperands.

Implementationsareexpectedtotraversearbitrarydepthswhen
processingtheRoption.Theonlylimitationondepthshouldbe
basedonrunningoutofphysicalstorageforkeepingtrackof
untraverseddirectories.

The1(one)optionwashistoricallyfoundinBSDandBSDderived
implementationsonly.ItisrequiredinthisvolumeofPOSIX.12008
sothatconformingapplicationsmightensurethatoutputisoneentry
perline,eveniftheoutputistoaterminal.

TheSoptionwasaddedinIssue7,buthadbeenprovidedbyseveral
implementationsformanyyears.Thedescriptiongiveninthestandard
documentshistoricpractice,butdoesnotmatchmuchofthe
documentationthatdescribeditsbehavior.Historicaldocumentation
typicallydescribeditassomethinglike:

SSortbysize(largestsizefirst)insteadofbyname.
Specialcharacterdevices(listedlast)aresortedbyname.

eventhoughthefiletypewasneverconsideredwhensortingthe
http://man7.org/linux/manpages/man1/ls.1p.html 12/15
3/6/2017 ls.1pLinuxmanualpage
eventhoughthefiletypewasneverconsideredwhensortingthe
output.Characterspecialfilesdotypicallysortclosetotheend
ofthelistbecausetheirfilesizeonmostimplementationsiszero.
Buttheyaresortedalphabeticallywithanyotherfilesthathappen
tohavethesamefilesize(zero),notsortedseparatelyandaddedto
theend.

ThisvolumeofPOSIX.12008isfrequentlysilentaboutwhathappens
whenmutuallyexclusiveoptionsarespecified.ExceptforR,d,and
f,thelsutilityisrequiredtoacceptmultipleoptionsfromeach
mutuallyexclusiveoptionsetwithouttreatingthemaserrorsandto
usethebehaviorspecifiedbythelastoptiongivenineachmutually
exclusiveset.Sincelsisoneofthemostaliasedcommands,itis
importantthattheimplementationperformintuitively.Forexample,
ifthealiaswere:

aliasls="lsC"

andtheusertypedls1(one),singletextcolumnoutputshould
result,notanerror.

Theg,l(ell),n,andooptionsarenotmutuallyexclusive
options.Theyallenablelongformatoutput.Theyworktogetherto
determinewhetherthefile'sowneriswritten(noifgispresent),
file'sgroupiswritten(noifoispresent),andifthefile's
grouporowneriswrittenwhetheritiswrittenasthename(default)
orastringrepresentationoftheUIDorGIDnumber(ifnis
present).TheC,m,x,and1(one)aremutuallyexclusiveoptions
andthefirstthreeofthesedisablelongformatoutput.The1(one)
optiondoesnotdirectlychangewhetherornotlongformatoutputis
enabled,butbyoverridingC,m,andx,itcanreenablelong
formatoutputthathadbeendisabledbyoneoftheseoptions.

EarlierversionsofthisstandarddidnotdescribetheBSDAoption
(likea,butdotanddotdotarenotwrittenout).Ithasbeenadded
duetowidespreadimplementation.

Implementationsmaymakeqthedefaultforterminalstoprevent
trojanhorseattacksonterminalswithspecialescapesequences.
Thisisnotrequiredbecause:

*Somecontrolcharactersmaybeusefulonsometerminals;for
example,asystemmightwritethemas"\001"or"^A".

*Specialbehaviorforterminalsisnotrelevanttoapplications
portability.

Anearlyproposalspecifiedthatthe
<optionalalternateaccessmethodflag>hadtobe'+'iftherewasan
alternateaccessmethodusedonthefileor<space>iftherewasnot.
Thiswaschangedtobe<space>ifthereisnotandasingleprintable
characterifthereis.Thiswasdoneforthreereasons:
http://man7.org/linux/manpages/man1/ls.1p.html 13/15
3/6/2017 ls.1pLinuxmanualpage
characterifthereis.Thiswasdoneforthreereasons:

1.Therearehistoricalimplementationsusingcharactersotherthan
'+'.

2.Thereareimplementationsthatvarythischaracterusedinthat
positiontodistinguishbetweenvariousalternateaccessmethods
inuse.

3.Thestandarddevelopersdidnotwanttoprecludefuture
specificationsthatmightneedawaytospecifymorethanone
alternateaccessmethod.

Nonetheless,implementationsprovidingasinglealternateaccess
methodareencouragedtouse'+'.

Earlierversionsofthisstandarddidnothavethekoption,which
meantthatthesoptioncouldnotbeusedportablyasitsblocksize
wasimplementationdefined,andtheunitsusedtospecifythenumber
ofblocksoccupiedbyfilesinadirectoryinanlsllistingwere
fixedas512byteunits.Thekoptionhasbeenaddedtoprovidea
wayforthesoptiontobeusedportably,andforconsistencyit
alsochangestheaforementionedunitsfrom512byteto1024byte.

The<dateandtime>fieldinthelformatisspecifiedonlyforthe
POSIXlocale.Asnoted,theformatcanbedifferentinotherlocales.
Nomechanismfordefiningthisispresentinthisvolumeof
POSIX.12008,astheappropriatevehicleisamessagingsystem;that
is,theformatshouldbespecifiedasa``message''.

FUTUREDIRECTIONStop

AllowingftoignoretheA,g,l,n,o,andsoptionsmaybe
removedinafutureversion.

SEEALSOtop

chmod(1p),find(1p)

TheBaseDefinitionsvolumeofPOSIX.12008,Section4.4,FileAccess
Permissions,Chapter8,EnvironmentVariables,Section12.2,Utility
SyntaxGuidelines,sys_stat.h(0p)

TheSystemInterfacesvolumeofPOSIX.12008,fstatat(3p)

COPYRIGHTtop

Portionsofthistextarereprintedandreproducedinelectronicform
fromIEEEStd1003.1,2013Edition,StandardforInformation
http://man7.org/linux/manpages/man1/ls.1p.html 14/15
3/6/2017 ls.1pLinuxmanualpage
fromIEEEStd1003.1,2013Edition,StandardforInformation
TechnologyPortableOperatingSystemInterface(POSIX),TheOpen
GroupBaseSpecificationsIssue7,Copyright(C)2013bythe
InstituteofElectricalandElectronicsEngineers,IncandTheOpen
Group.(ThisisPOSIX.12008withthe2013TechnicalCorrigendum1
applied.)Intheeventofanydiscrepancybetweenthisversionand
theoriginalIEEEandTheOpenGroupStandard,theoriginalIEEEand
TheOpenGroupStandardistherefereedocument.Theoriginal
Standardcanbeobtainedonlineathttp://www.unix.org/online.html.

Anytypographicalorformattingerrorsthatappearinthispageare
mostlikelytohavebeenintroducedduringtheconversionofthe
sourcefilestomanpageformat.Toreportsucherrors,see
https://www.kernel.org/doc/manpages/reporting_bugs.html.

IEEE/TheOpenGroup2013LS(1P)

HTMLrenderingcreated20161212byMichaelKerrisk,authorofTheLinux
ProgrammingInterface,maintaineroftheLinuxmanpagesproject.
FordetailsofindepthLinux/UNIXsystemprogrammingtrainingcoursesthatI
teach,lookhere.
HostingbyjambitGmbH.

http://man7.org/linux/manpages/man1/ls.1p.html 15/15