Author image Leon Timmermans


Net::FSP - A client implementation of the File Service Protocol


This documentation refers to Net::FSP version 0.16


 use Net::FSP;
 my $fsp = Net::FSP->new("hostname", { remote_port => 21 });
 #do something
 $fsp->upload_file('foo', 'foo');


FSP is a very lightweight UDP based protocol for transferring files. FSP has many benefits over FTP, mainly for running anonymous archives. FSP protocol is valuable in all kinds of environments because it is one of the few protocols that is not aggressive about bandwidth while at the same time being sufficiently fault tolerant. Net::FSP is a class implementing the client side of FSP.


new($remote_host, {...})

Creates a new Net::FSP object. As its optional second argument it takes a hashref of the following members:


The remote port to connect to. It defaults to 21.


The local address to bind to. This parameter is usually only needed on multihomed connections. By default a socket isn't bound to a particular interface.


The local port to bind the connection to. It defaults to 0 (random).


The minimal delay in seconds before a request is resent. It defaults to 1.34.


The factor with which the delay increases each time a request goes unresponded. It defaults to 1.5.


The maximal delay for resending a request. If the delay would have been larger than this an exception is thrown. It defaults to 60 seconds.


Your password for this server. It defaults to undef (none).


The maximal size of the payload. It defaults to 1024. Some servers may not support values higher than 1024. Setting this higher than the MTU - 12 is not recommended.


This sets the protocol used as network layer. Currently the only supported values are ipv4 (the default) and ipv6 (this requires having the Socket6 module installed). As of writing no FSP server supports ipv6 yet though.


The size with which data is requested from the server. It defaults to max_payload_size.


The size with which data is written to the server. It defaults to max_payload_size.


The size with which directories are read from the server. It defaults to max_payload_size.


This method returns the current working directory on the server.


This method changes the current working directory on the server. It returns the previous working directory.


This method releases the connection to the FSP server. Note that this doesn't mean the connection is closed, it only means other clients from the same host can now contact the server.


This method returns the full version of the server.


This method returns some information about the configuration of the server. It returns a hashref with the following elements: logging, read-only, reverse-lookup, private-mode throughput-control extra-data.

download_file($file_name, $sink)

This method downloads file $file_name to $sink. $sink must either be an untainted filename, a filehandle or a callback function.


This method downloads file $file_name and returns it as a string. Using this on large files is not recommended.

grab_file($file_name, $sink)

This method downloads file $file_name, and deletes it at when this is done. These actions are considered atomic by the server. Its arguments work as in download_file.


This method returns a list of files and subdirectories of directory $directory_name. The entries in the lists are either a Net::FSP::File or a Net::FSP::Dir for files and directories respectively.


In list context this returns a list of: the modification time (in unix format), the size (in bytes), and the type (either 'file' or 'dir') of file $file_name. In scalar context it returns either a Net::FSP::File or a Net::FSP::Dir object for files and directories respectively.

upload_file($file_name, $source)

This method uploads file $file_name to the server. $source must either be a filename, a filehandle or a callback function.

open_file($file_name, $mode)

Open a file and return a filehandle.


This method deletes file $file_name.


This method deletes directory $directory_name.


This method returns the readme for a directory, if there is any.


This method returns the directory's protection. It returns a hash reference with the elements owner, delete, create, mkdir, private, readme, list and rename.

set_protection($directory_name, $mode)

This method changes the permission of directory $directory_name for public users. It's mode argument is consists of two characters. The first byte is + or -, to indicate whether the permission is granted or revoked. The second byte contains a c, d, g, m, l or r for the permission to create files, delete files, get files, create directories, list the directory or rename files. Its return value is the same as get_protection.


This method creates a directory named $directory_name.

move_file($old_name, $new_name)

This method moves $old_name to $new_name.


If the server encounters an error, it will be thrown as an exception string, prepended by 'Received error from server: '. Unfortunately the content of these errors are not well documented. Since the protocol is mostly stateless one can usually assume these errors have no effect on later requests. If the server doesn't respond at all, a 'Remote server not responding.' exception will eventually be thrown.


This module depends on perl version 5.6 or higher.


FSP connections can not be shared between threads. Other than that, there are no known problems in this module. Please report problems to Leon Timmermans ( Patches are welcome.


This module has no configuration file. All configuration is done through the constructor. Some utility functions to make used of the environment are defined in Net::FSP::Util.


This module has no known incompatibilities.


Leon Timmermans,


The protocol is described at


Copyright (c) 2005, 2008 Leon Timmermans. All rights reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.