README

goftp

Build Status Coverage Status Go ReportCard Go Reference

A FTP client package for Go

Install

go get -u github.com/jlaffaye/ftp

Documentation

https://pkg.go.dev/github.com/jlaffaye/ftp

Example

c, err := ftp.Dial("ftp.example.org:21", ftp.DialWithTimeout(5*time.Second))
if err != nil {
    log.Fatal(err)
}

err = c.Login("anonymous", "anonymous")
if err != nil {
    log.Fatal(err)
}

// Do something with the FTP conn

if err := c.Quit(); err != nil {
    log.Fatal(err)
}

Store a file example

data := bytes.NewBufferString("Hello World")
err = c.Stor("test-file.txt", data)
if err != nil {
	panic(err)
}

Read a file example

r, err := c.Retr("test-file.txt")
if err != nil {
	panic(err)
}
defer r.Close()

buf, err := ioutil.ReadAll(r)
println(string(buf))
Expand ▾ Collapse ▴

Documentation

Overview

    Package ftp implements a FTP client as described in RFC 959.

    A textproto.Error is returned for errors at the protocol level.

    Index

    Constants

    View Source
    const (
    	StatusInitiating    = 100
    	StatusRestartMarker = 110
    	StatusReadyMinute   = 120
    	StatusAlreadyOpen   = 125
    	StatusAboutToSend   = 150
    
    	StatusCommandOK             = 200
    	StatusCommandNotImplemented = 202
    	StatusSystem                = 211
    	StatusDirectory             = 212
    	StatusFile                  = 213
    	StatusHelp                  = 214
    	StatusName                  = 215
    	StatusReady                 = 220
    	StatusClosing               = 221
    	StatusDataConnectionOpen    = 225
    	StatusClosingDataConnection = 226
    	StatusPassiveMode           = 227
    	StatusLongPassiveMode       = 228
    	StatusExtendedPassiveMode   = 229
    	StatusLoggedIn              = 230
    	StatusLoggedOut             = 231
    	StatusLogoutAck             = 232
    	StatusAuthOK                = 234
    	StatusRequestedFileActionOK = 250
    	StatusPathCreated           = 257
    
    	StatusUserOK             = 331
    	StatusLoginNeedAccount   = 332
    	StatusRequestFilePending = 350
    
    	StatusNotAvailable             = 421
    	StatusCanNotOpenDataConnection = 425
    	StatusTransfertAborted         = 426
    	StatusInvalidCredentials       = 430
    	StatusHostUnavailable          = 434
    	StatusFileActionIgnored        = 450
    	StatusActionAborted            = 451
    	Status452                      = 452
    
    	StatusBadCommand              = 500
    	StatusBadArguments            = 501
    	StatusNotImplemented          = 502
    	StatusBadSequence             = 503
    	StatusNotImplementedParameter = 504
    	StatusNotLoggedIn             = 530
    	StatusStorNeedAccount         = 532
    	StatusFileUnavailable         = 550
    	StatusPageTypeUnknown         = 551
    	StatusExceededStorage         = 552
    	StatusBadFileName             = 553
    )

      FTP status codes, defined in RFC 959

      Variables

      This section is empty.

      Functions

      func StatusText

      func StatusText(code int) string

        StatusText returns a text for the FTP status code. It returns the empty string if the code is unknown.

        Types

        type DialOption

        type DialOption struct {
        	// contains filtered or unexported fields
        }

          DialOption represents an option to start a new connection with Dial

          func DialWithContext

          func DialWithContext(ctx context.Context) DialOption

            DialWithContext returns a DialOption that configures the ServerConn with specified context The context will be used for the initial connection setup

            func DialWithDebugOutput

            func DialWithDebugOutput(w io.Writer) DialOption

              DialWithDebugOutput returns a DialOption that configures the ServerConn to write to the Writer everything it reads from the server

              func DialWithDialFunc

              func DialWithDialFunc(f func(network, address string) (net.Conn, error)) DialOption

                DialWithDialFunc returns a DialOption that configures the ServerConn to use the specified function to establish both control and data connections

                If used together with the DialWithNetConn option, the DialWithNetConn takes precedence for the control connection, while data connections will be established using function specified with the DialWithDialFunc option

                func DialWithDialer

                func DialWithDialer(dialer net.Dialer) DialOption

                  DialWithDialer returns a DialOption that configures the ServerConn with specified net.Dialer

                  func DialWithDisabledEPSV

                  func DialWithDisabledEPSV(disabled bool) DialOption

                    DialWithDisabledEPSV returns a DialOption that configures the ServerConn with EPSV disabled Note that EPSV is only used when advertised in the server features.

                    func DialWithDisabledMLSD

                    func DialWithDisabledMLSD(disabled bool) DialOption

                      DialWithDisabledMLSD returns a DialOption that configures the ServerConn with MLSD option disabled

                      This is useful for servers which advertise MLSD (eg some versions of Serv-U) but don't support it properly.

                      func DialWithDisabledUTF8

                      func DialWithDisabledUTF8(disabled bool) DialOption

                        DialWithDisabledUTF8 returns a DialOption that configures the ServerConn with UTF8 option disabled

                        func DialWithExplicitTLS

                        func DialWithExplicitTLS(tlsConfig *tls.Config) DialOption

                          DialWithExplicitTLS returns a DialOption that configures the ServerConn to be upgraded to TLS See DialWithTLS for general TLS documentation

                          func DialWithLocation

                          func DialWithLocation(location *time.Location) DialOption

                            DialWithLocation returns a DialOption that configures the ServerConn with specified time.Location The location is used to parse the dates sent by the server which are in server's timezone

                            func DialWithNetConn

                            func DialWithNetConn(conn net.Conn) DialOption

                              DialWithNetConn returns a DialOption that configures the ServerConn with the underlying net.Conn

                              func DialWithTLS

                              func DialWithTLS(tlsConfig *tls.Config) DialOption

                                DialWithTLS returns a DialOption that configures the ServerConn with specified TLS config

                                If called together with the DialWithDialFunc option, the DialWithDialFunc function will be used when dialing new connections but regardless of the function, the connection will be treated as a TLS connection.

                                func DialWithTimeout

                                func DialWithTimeout(timeout time.Duration) DialOption

                                  DialWithTimeout returns a DialOption that configures the ServerConn with specified timeout

                                  type Entry

                                  type Entry struct {
                                  	Name   string
                                  	Target string // target of symbolic link
                                  	Type   EntryType
                                  	Size   uint64
                                  	Time   time.Time
                                  }

                                    Entry describes a file and is returned by List().

                                    type EntryType

                                    type EntryType int

                                      EntryType describes the different types of an Entry.

                                      const (
                                      	EntryTypeFile EntryType = iota
                                      	EntryTypeFolder
                                      	EntryTypeLink
                                      )

                                        The differents types of an Entry

                                        func (EntryType) String

                                        func (t EntryType) String() string

                                          String returns the string representation of EntryType t.

                                          type Response

                                          type Response struct {
                                          	// contains filtered or unexported fields
                                          }

                                            Response represents a data-connection

                                            func (*Response) Close

                                            func (r *Response) Close() error

                                              Close implements the io.Closer interface on a FTP data connection. After the first call, Close will do nothing and return nil.

                                              func (*Response) Read

                                              func (r *Response) Read(buf []byte) (int, error)

                                                Read implements the io.Reader interface on a FTP data connection.

                                                func (*Response) SetDeadline

                                                func (r *Response) SetDeadline(t time.Time) error

                                                  SetDeadline sets the deadlines associated with the connection.

                                                  type ServerConn

                                                  type ServerConn struct {
                                                  	// contains filtered or unexported fields
                                                  }

                                                    ServerConn represents the connection to a remote FTP server. A single connection only supports one in-flight data connection. It is not safe to be called concurrently.

                                                    func Connect

                                                    func Connect(addr string) (*ServerConn, error)

                                                      Connect is an alias to Dial, for backward compatibility

                                                      func Dial

                                                      func Dial(addr string, options ...DialOption) (*ServerConn, error)

                                                        Dial connects to the specified address with optional options

                                                        func DialTimeout

                                                        func DialTimeout(addr string, timeout time.Duration) (*ServerConn, error)

                                                          DialTimeout initializes the connection to the specified ftp server address.

                                                          It is generally followed by a call to Login() as most FTP commands require an authenticated user.

                                                          func (*ServerConn) Append

                                                          func (c *ServerConn) Append(path string, r io.Reader) error

                                                            Append issues a APPE FTP command to store a file to the remote FTP server. If a file already exists with the given path, then the content of the io.Reader is appended. Otherwise, a new file is created with that content.

                                                            Hint: io.Pipe() can be used if an io.Writer is required.

                                                            func (*ServerConn) ChangeDir

                                                            func (c *ServerConn) ChangeDir(path string) error

                                                              ChangeDir issues a CWD FTP command, which changes the current directory to the specified path.

                                                              func (*ServerConn) ChangeDirToParent

                                                              func (c *ServerConn) ChangeDirToParent() error

                                                                ChangeDirToParent issues a CDUP FTP command, which changes the current directory to the parent directory. This is similar to a call to ChangeDir with a path set to "..".

                                                                func (*ServerConn) CurrentDir

                                                                func (c *ServerConn) CurrentDir() (string, error)

                                                                  CurrentDir issues a PWD FTP command, which Returns the path of the current directory.

                                                                  func (*ServerConn) Delete

                                                                  func (c *ServerConn) Delete(path string) error

                                                                    Delete issues a DELE FTP command to delete the specified file from the remote FTP server.

                                                                    func (*ServerConn) FileSize

                                                                    func (c *ServerConn) FileSize(path string) (int64, error)

                                                                      FileSize issues a SIZE FTP command, which Returns the size of the file

                                                                      func (*ServerConn) List

                                                                      func (c *ServerConn) List(path string) (entries []*Entry, err error)

                                                                        List issues a LIST FTP command.

                                                                        func (*ServerConn) Login

                                                                        func (c *ServerConn) Login(user, password string) error

                                                                          Login authenticates the client with specified user and password.

                                                                          "anonymous"/"anonymous" is a common user/password scheme for FTP servers that allows anonymous read-only accounts.

                                                                          func (*ServerConn) Logout

                                                                          func (c *ServerConn) Logout() error

                                                                            Logout issues a REIN FTP command to logout the current user.

                                                                            func (*ServerConn) MakeDir

                                                                            func (c *ServerConn) MakeDir(path string) error

                                                                              MakeDir issues a MKD FTP command to create the specified directory on the remote FTP server.

                                                                              func (*ServerConn) NameList

                                                                              func (c *ServerConn) NameList(path string) (entries []string, err error)

                                                                                NameList issues an NLST FTP command.

                                                                                func (*ServerConn) NoOp

                                                                                func (c *ServerConn) NoOp() error

                                                                                  NoOp issues a NOOP FTP command. NOOP has no effects and is usually used to prevent the remote FTP server to close the otherwise idle connection.

                                                                                  func (*ServerConn) Quit

                                                                                  func (c *ServerConn) Quit() error

                                                                                    Quit issues a QUIT FTP command to properly close the connection from the remote FTP server.

                                                                                    func (*ServerConn) RemoveDir

                                                                                    func (c *ServerConn) RemoveDir(path string) error

                                                                                      RemoveDir issues a RMD FTP command to remove the specified directory from the remote FTP server.

                                                                                      func (*ServerConn) RemoveDirRecur

                                                                                      func (c *ServerConn) RemoveDirRecur(path string) error

                                                                                        RemoveDirRecur deletes a non-empty folder recursively using RemoveDir and Delete

                                                                                        func (*ServerConn) Rename

                                                                                        func (c *ServerConn) Rename(from, to string) error

                                                                                          Rename renames a file on the remote FTP server.

                                                                                          func (*ServerConn) Retr

                                                                                          func (c *ServerConn) Retr(path string) (*Response, error)

                                                                                            Retr issues a RETR FTP command to fetch the specified file from the remote FTP server.

                                                                                            The returned ReadCloser must be closed to cleanup the FTP data connection.

                                                                                            func (*ServerConn) RetrFrom

                                                                                            func (c *ServerConn) RetrFrom(path string, offset uint64) (*Response, error)

                                                                                              RetrFrom issues a RETR FTP command to fetch the specified file from the remote FTP server, the server will not send the offset first bytes of the file.

                                                                                              The returned ReadCloser must be closed to cleanup the FTP data connection.

                                                                                              func (*ServerConn) Stor

                                                                                              func (c *ServerConn) Stor(path string, r io.Reader) error

                                                                                                Stor issues a STOR FTP command to store a file to the remote FTP server. Stor creates the specified file with the content of the io.Reader.

                                                                                                Hint: io.Pipe() can be used if an io.Writer is required.

                                                                                                func (*ServerConn) StorFrom

                                                                                                func (c *ServerConn) StorFrom(path string, r io.Reader, offset uint64) error

                                                                                                  StorFrom issues a STOR FTP command to store a file to the remote FTP server. Stor creates the specified file with the content of the io.Reader, writing on the server will start at the given file offset.

                                                                                                  Hint: io.Pipe() can be used if an io.Writer is required.

                                                                                                  func (*ServerConn) Walk

                                                                                                  func (c *ServerConn) Walk(root string) *Walker

                                                                                                    Walk prepares the internal walk function so that the caller can begin traversing the directory

                                                                                                    type Walker

                                                                                                    type Walker struct {
                                                                                                    	// contains filtered or unexported fields
                                                                                                    }

                                                                                                      Walker traverses the directory tree of a remote FTP server

                                                                                                      func (*Walker) Err

                                                                                                      func (w *Walker) Err() error

                                                                                                        Err returns the error, if any, for the most recent attempt by Next to visit a file or a directory. If a directory has an error, the walker will not descend in that directory

                                                                                                        func (*Walker) Next

                                                                                                        func (w *Walker) Next() bool

                                                                                                          Next advances the Walker to the next file or directory, which will then be available through the Path, Stat, and Err methods. It returns false when the walk stops at the end of the tree.

                                                                                                          func (*Walker) Path

                                                                                                          func (w *Walker) Path() string

                                                                                                            Path returns the path to the most recent file or directory visited by a call to Next. It contains the argument to Walk as a prefix; that is, if Walk is called with "dir", which is a directory containing the file "a", Path will return "dir/a".

                                                                                                            func (*Walker) SkipDir

                                                                                                            func (w *Walker) SkipDir()

                                                                                                              SkipDir tells the Next function to skip the currently processed directory

                                                                                                              func (*Walker) Stat

                                                                                                              func (w *Walker) Stat() *Entry

                                                                                                                Stat returns info for the most recent file or directory visited by a call to Step.