ftp

Object to connect to FTP server and access its files

expand all in page

Description

Connect to an FTP server by calling the ftp function, which creates an FTP object. To access a particular FTP account on the server, specify a user name and password. Then use the FTP object to upload and download files. You also can create, delete, and navigate to different folders on the server. To close the connection, use the close function.

Note

Because FTP is not a secure protocol, the FTP object does not encrypt your user name, your password, or any data you download from or upload to an FTP server. If you require a secure FTP connection, then use an SFTP client provided by your system.

Creation

Syntax

ftpobj = ftp(host)
ftpobj = ftp(host,username,password)
ftpobj = ftp(host,username,password,Name,Value)

Description

example

ftpobj = ftp(host) opens a connection to the FTP server host and stores the connection in FTP object ftpobj. To use this syntax, host must support anonymous connections.

ftpobj = ftp(host,username,password) accesses the FTP account with the specified user name and password.

ftpobj = ftp(host,username,password,Name,Value) specifies additional input arguments using one or more name-value pair arguments. For example, you can specify the value of 'System' as 'WINDOWS' to connect to an FTP server that runs a Windows® operating system. You also can specify the value of 'LocalDataConnectionMethod' to change the connection mode from passive to active mode.

Input Arguments

expand all

Name of the FTP server, specified as a character vector or string scalar.

To specify an alternate port number for the connection, append a colon (:) and the port number to host. The default port number for FTP servers is 21.

Typically, the name of the server starts with 'ftp', as in 'ftp.example.com'. However, this practice is a convention, not a technical requirement. If the name of the FTP server starts with a different prefix, then you simply specify host as that name. Do not append 'ftp://' to the name to specify the FTP protocol.

Example: ftpobj = ftp('ftp.example.com') opens an anonymous connection to ftp.example.com.

Example: ftpobj = ftp('www.example.com') opens a connection if the server www.example.com is configured to provide FTP service.

Example: ftpobj = ftp('ftp.example.com:34') opens a connection using port number 34.

Name of an authorized account on the FTP server, specified as a character vector or string scalar. The FTP object sends username as plain text.

Password for an authorized account, specified as a character vector or string scalar. The FTP object sends password as plain text.

Example: ftpobj = ftp('ftp.example.com','nlee','mypassword') opens a connection for the user nlee using the password mypassword.

Name-Value Pair Arguments

Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside quotes. You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

Example: ftpobj = ftp('ftp.example.com','nlee','mypassword','System','WINDOWS') opens a connection to an FTP server that runs a Windows-based operating system.

Type of operating system running on the FTP server, specified as the comma-separated pair consisting of 'System' and either 'UNIX' or 'WINDOWS'.

Connection mode, specified as the comma-separated pair consisting of 'LocalDataConnectionMethod' and either 'passive' or 'active'.

There are two modes for establishing an FTP connection.

  • 'active' — Your machine establishes a channel for commands, but the FTP server establishes a channel for data. Active mode can be a problem if, for example, your machine is protected by a firewall and does not allow unauthorized session requests from external sources.

  • 'passive' — Your machine establishes both channels. After establishing the command channel, your machine requests that the FTP server start listening on a port, so that your machine can connect to that port.

The default mode is 'passive' because most modern FTP implementations use passive mode. But to connect to some legacy servers, you might need to specify active mode.

Object Functions

asciiSet FTP transfer mode to ASCII
binarySet FTP transfer mode to binary
cdChange or view current folder on FTP server
closeClose connection to FTP server
deleteDelete file on FTP server
dirList folder contents on FTP server
mgetDownload files from FTP server
mkdirMake new folder on FTP server
mputUpload file or folder to FTP server
renameRename file on FTP server
rmdirRemove folder on FTP server

Examples

collapse all

Open Live Script

To open a connection to an FTP server, create an FTP object. Use the FTP object to download a file and list the contents of subfolders on the server. At the end of the FTP session, close the connection.

First, connect to the National Centers for Environmental Information (NCEI) FTP server.

ftpobj = ftp('ftp.ngdc.noaa.gov')
ftpobj = 

  FTP Object
     host: ftp.ngdc.noaa.gov
     user: anonymous
      dir: /
     mode: binary

List the contents of the top-level folder.

dir(ftpobj)
 
DMSP                         Solid_Earth                  google12c4c939d7b90761.html  mgg                          
INDEX.txt                    coastwatch                   hazards                      pub                          
README.txt                   dmsp4alan                    index.html                   tmp                          
STP                          ftp.html                     international                wdc                          
Snow_Ice                     geomag                       ionosonde

Download the README.txt file from the FTP server. The mget function downloads a copy to your current MATLAB® folder.

mget(ftpobj,'README.txt');

Read the contents of your copy of README.txt using the fileread function. Split the text into lines using the splitlines function and display the first four lines.

readme = fileread('README.txt');
readme = splitlines(readme);
readme(1:4)
ans = 4×1 cell array
    {'                 Welcome to the '                                }
    {'    NOAA/National Centers for Environmental Information (NCEI), '}
    {'    formerly the National Geophysical Data Center (NGDC)'        }
    {'                    FTP area'                                    }

List the contents of a subfolder using the dir function.

dir(ftpobj,'STP')
 
ANOMALIES                   NOAA                        Solid_Earth                 publications                
DMSP                        SEIS                        aavso_22nov16               satellite_data              
ECLIPSE                     SGD                         aeronomy                    space-weather               
GEOMAGNETIC_DATA            SOLAR_DATA                  cdroms                      space_environment_modeling  
GOIN                        SPIDR                       goesr                       swpc_products               
GPS_GNSS                    STEP                        ionosonde                   tivoli                      
IONOSPHERE                  SWA                         log.txt

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

cd(ftpobj,'STP/space-weather')
ans = 
'/STP/space-weather'

List the contents of the current folder.

dir(ftpobj)
 
aurora-airglow           documentation            interplanetary-data      online-publications      solar-data               
denig-files              geomagnetic-data         ionospheric-data         satellite-data           spacecraft-environments

Close the connection to the FTP server. You also can close the connection by deleting the FTP object or letting the connection time out.

close(ftpobj)

FTP service courtesy of the National Centers for Environmental Information (NCEI). See the NCEI Privacy Policy, Disclaimer, and Copyright for NCEI terms of service.

Tips

  • The FTP object does not support proxy server settings.

  • While it is unnecessary to specify the 'System',systemKey name-value pair, the FTP dir function might return less information if the FTP object is not configured for the operating system running on the FTP server. In such cases, dir might return a structure array with some empty fields. In that case, call ftp again and specify the correct value for systemKey.

Algorithms

The code for the FTP object is based on code from the Apache™ Project.

In particular, the ftp function configures properties for FTP connections as specified by the Apache FTPClientConfig class. Any settable property of the FTPClientConfig class can be set using the ftp function with the corresponding name-value pair argument.

See Also

| | | |

Topics

Introduced before R2006a

MATLAB Documentation

Support