dir

List folder contents on SFTP or FTP server

Syntax

dir(s)

dir(s,folder)

dir(s,"ParseOutput",tf)

listing = dir(___)

Description

dir(s) lists the contents of the current folder on the SFTP or FTP server associated with s. The contents of the current folder can be files and other folders.

dir(s,folder) lists the contents of the specified folder.

dir(s,"ParseOutput",tf) returns the raw LIST command output as a string array.

listing = dir(___) returns a structure array that contains the name, modification date, and size of each item. You can use this syntax with the input arguments of any of the previous syntaxes.

Examples

List Contents of Folders

Open a connection to an SFTP server by creating an SFTP object. Download a file and list the contents of subfolders on the server using the SFTP object.

First, connect to the example SFTP server.

s = sftp("sftp.example_galapagos.net","maria.silva")

  SFTP with properties:

                         Host: "sftp.example_galapagos.net"
                     Username: "maria.silva"
                         Port: 22
                 ServerSystem: "unix"
                 DatetimeType: "datetime"
                 ServerLocale: "en_US"
                 DirParserFcn: @matlab.io.ftp.parseDirListingForUnix
       RemoteWorkingDirectory: "/home/maria.silva"

List the contents of the top-level folder.

dir(s)

 
air_quality                  fish                        insects                       README.txt
birds                        INDEX.txt                   mammals                       reptiles
climate                      index.html                  rainfall                      sftp.html
 

List the contents of a subfolder using the dir function.

dir(s,"home/maria.silva/birds")

 
albatrosses                 ducks                       herons                     parrots 
avocets_stilts              falcons                     kingfishers                pelicans
barn_owls                   flamingos                   mockingbirds               penguins 
blackbirds                  frigatebirds                nightjars                  pheasants 
boobies                     grebes                      northern_storm_petrels     pigeons 
cardinal grosbeaks          guineafowl                  osprey                     plovers 
cormorants                  gulls                       owls                       rails
cuckoos                     hawks                       oystercatcher              sandpipers
 

Change to a subfolder using the cd function. The output from cd is the path to the current folder on the SFTP server, not your current MATLAB folder.

cd(s,"home/maria.silva/birds/herons")

ans = 
"home/maria.silva/birds/herons"

List the contents of the current folder.

dir(s)

documentation             great_egret_data              migration_patterns
great_blue_heron_data     green_heron_data              nesting_behaviors 

Parse LIST Command Output

Parse the raw output of the SFTP server's LIST command.

First, connect to the example SFTP server.

s = sftp("sftp.example_galapagos.net","maria.silva")

  SFTP with properties:

                         Host: "sftp.example_galapagos.net"
                     Username: "maria.silva"
                         Port: 22
                 ServerSystem: "unix"
                 DatetimeType: "datetime"
                 ServerLocale: "en_US"
                 DirParserFcn: @matlab.io.ftp.parseDirListingForUnix
       RemoteWorkingDirectory: "/home/maria.silva"

List the contents of the current folder on the server. Assign the output struct to the variable a.

a = dir(s)

a=12×1 struct array with fields:
    name
    isdir
    bytes
    date
    datenum

Parse the raw output of the LIST command. Assign the output string to the variable b.

b = dir(s,"ParseOutput",false)

b = 17x1 string
    "lrwxrwxrwx    1       sftp            32 Nov 05  2014 air_quality"
    "-rw-r--r--   32       sftp          1516 Mar 08  2017 birds"
    "-rw-rw-r--    1       sftp          3766 Apr 18  2020 climate"
    "drwxr-xr-x   36       sftp            31 Jun 04  2016 fish"
    "drwxr-xr-x    1       sftp            52 Oct 08  2009 INDEX.txt"
    "drwxr-xr-x    1       sftp            75 Jan 12  2015 index.html"
    "drwxrwsr-x    5       sftp           673 Jul 02  2018 insects"
    "drwxrwsr-x    3       sftp             2 Jun 11  2017 mammals"
    "-rw-rw-r--    2       sftp          9036 Apr 08  2014 rainfall"
    "drwxrwsr-x    1       sftp            11 Jan 10  2019 README.txt"
    "-rw-rw-r--    3       sftp            43 Sep 14  2021 reptiles"
    "drwxrwxr-x    1       sftp          5328 Oct 02  2009 sftp.html"

List Details of Contents

List details of the contents on an SFTP server. The dir function can return a structure array that contains the name, modification date, and size of each item in the specified folder.

First, connect to the example SFTP server.

s = sftp("sftp.example_galapagos.net","maria.silva")

  SFTP with properties:

                         Host: "sftp.example_galapagos.net"
                     Username: "maria.silva"
                         Port: 22
                 ServerSystem: "unix"
                 DatetimeType: "datetime"
                 ServerLocale: "en_US"
                 DirParserFcn: @matlab.io.ftp.parseDirListingForUnix
       RemoteWorkingDirectory: "/home/maria.silva"

Return details about the items in the top-level folder on the SFTP server. Some items are files and the others are folders.

listing = dir(s)

listing =12×1 struct array with fields:
    name
    isdir
    bytes
    date
    datenum

Display details about the first item in the current folder, which is a folder named air_quality.

listing(1)

ans = struct with fields:
       name: 'air_quality'
      bytes: 64
      isdir: 1
       date: '05-Nov-2014 00:00:00'
    datenum: 735908

Input Arguments

s — Connection to SFTP or FTP server

SFTP object | FTP object

Connection to an SFTP or FTP server, specified as an SFTP object or an FTP object.

folder — Name of target folder

character vector | string scalar

Name of the target folder on the SFTP or FTP server, specified as a character vector or string scalar. To specify the folder above the current one, use '..'.

tf — Return the raw LIST command output as a string array

true (default) | false

Return the raw LIST command output as a string array, specified as true or false.

Output Arguments

listing — Content attributes

structure array

Content attributes, returned as an m-by-1 structure array, where m is the number of items in the folder.

This table shows the fields in the structure.

Field Name	Description	Data Type
name	File or folder name	char
bytes	Size of the item in bytes	double
isdir	1 if name is a folder; 0 if name is a file	logical
date	Modification date timestamp	char
datenum	Modification date as serial date number	double

Tips

• The dir function might return a structure array in which the last four fields are empty or missing. When dir returns a structure with missing information, it might mean the SFTP or FTP object is not configured for the operating system that is running on the SFTP or FTP server. By default, an SFTP or FTP object is configured to connect to a server running a UNIX^® operating system.

Version History

Introduced before R2006a