ftp

package module

v2.0.0 Latest Latest Go to latest Published: Feb 17, 2025 License: ISC Imports: 11 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/snus8bit/ftp

README ¶

goftp

A FTP client package for Go

Install

go get -u 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)
}

buf, err := ioutil.ReadAll(r)
println(string(buf))

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
func StatusText(code int) string
type DialOption
type Entry
type EntryType
type Response
type Responser
type ServerConn
- func Dial(ctx context.Context, addr string, options ...DialOption) (*ServerConn, error)
- func DialTimeout(ctx context.Context, addr string, timeout time.Duration) (*ServerConn, error)

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
	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 DialWithDataConnectionTimeout ¶

func DialWithDataConnectionTimeout(timeout time.Duration) DialOption

DialWithDataConnectionTimeout returns a DialOption that configures the ServerConn with timeout for reading from data connection. It only affects data socket which is internally created for commands like LIST. It is "dynamic", which means it is restarted after each data portion arrives.

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(ctx context.Context, 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 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

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 Responser ¶

type Responser interface {
	io.Reader
	io.Closer
	// SetDeadline sets the deadlines associated with the connection.
	SetDeadline(t time.Time) error
}

Responser interface on a data-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 Dial ¶

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

Dial connects to the specified address with optional options

func DialTimeout ¶

func DialTimeout(ctx context.Context, 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) ChangeDir ¶

func (c *ServerConn) ChangeDir(ctx context.Context, 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(ctx context.Context) 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(ctx context.Context) (string, error)

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

func (*ServerConn) Delete ¶

func (c *ServerConn) Delete(ctx context.Context, path string) (code int, err error)

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

func (*ServerConn) FileSize ¶

func (c *ServerConn) FileSize(ctx context.Context, path string) (int64, error)

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

func (*ServerConn) List ¶

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

List issues a LIST FTP command.

func (c *ServerConn) Login(ctx context.Context, 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(ctx context.Context) error

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

func (*ServerConn) MakeDir ¶

func (c *ServerConn) MakeDir(ctx context.Context, path string) (code int, err error)

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

func (*ServerConn) NameList ¶

func (c *ServerConn) NameList(ctx context.Context, path string) (entries []string, err error)

NameList issues an NLST FTP command.

func (*ServerConn) NoOp ¶

func (c *ServerConn) NoOp(ctx context.Context) 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(ctx context.Context, path string) (code int, err error)

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

func (*ServerConn) RemoveDirRecur ¶

func (c *ServerConn) RemoveDirRecur(ctx context.Context, path string) (code int, err error)

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

func (*ServerConn) Rename ¶

func (c *ServerConn) Rename(ctx context.Context, from, to string) (code int, err error)

Rename renames a file on the remote FTP server. if code > 0 then it's not a connection/protocol error. It's a servere reply error like 553 file already exists

func (*ServerConn) Retr ¶

func (c *ServerConn) Retr(ctx context.Context, path string) (Responser, 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(ctx context.Context, path string, offset uint64) (Responser, 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.