Trivial File Transfer Protocol (TFTP) API

The TFTP client library provides an API to read files from and to write files to remote servers using the Trivial File Transfer Protocol (TFTP). More...

Data Structures
struct	tftp_options
	This structure represents TFTP options negotiated between client and server. More...
struct	tftp_net_config
	This structure represents configuration value used by the TFTP client. More...

Macros
#define	TFTP_RFC1350_BLOCK_SIZE   512
	This block size meets RFC 1350 and avoids the sending of the blksize option to the TFTP server.
#define	TFTP_RFC1350_WINDOW_SIZE   1
	This window size avoids the sending of the windowsize option to the TFTP server.
#define	TFTP_DEFAULT_BLOCK_SIZE   1456
	This block size is suggested in RFC 2348 and is used as default if no different block size is provided.
#define	TFTP_DEFAULT_WINDOW_SIZE   8
	This window size is suggested in RFC 2348 and is used as default if no different window size is provided.

Typedefs
typedef struct tftp_options	tftp_options
	This structure represents TFTP options negotiated between client and server.
typedef struct tftp_net_config	tftp_net_config
	This structure represents configuration value used by the TFTP client.

Functions
void	tftp_initialize_net_config (tftp_net_config *config)
	Set all members of a tftp_net_config structure to their default values.
int	tftp_open (const char *hostname, const char *path, bool is_for_reading, const tftp_net_config *config, void **tftp_handle)
	Opens and starts a TFTP client session to read or write a single file.
ssize_t	tftp_read (void *tftp_handle, void *buffer, size_t count)
	Read data from a TFTP server.
ssize_t	tftp_write (void *tftp_handle, const void *buffer, size_t count)
	Write data to a TFTP server.
int	tftp_close (void *tftp_handle)
	Close a TFTP client connection.

Detailed Description

The TFTP client library provides an API to read files from and to write files to remote servers using the Trivial File Transfer Protocol (TFTP).

See the RTEMS Filesystem Design Guide Chapter Trivial FTP Client Filesystem.

Usage as TFTP File System

To open /bootfiles/image on hostname for reading:

fd = open ("/TFTP/hostname:bootfiles/image", O_RDONLY);

The TFTP is the mount path and the hostname must be

• an IPv4 address (like 127.0.0.1) or
• the (full-qualified) name of an IPv4 host (acceptable to gethostbyname())

IPv6 is currently not supported. bootfiles/image is a path on the TFTP server hostname where the file (here image) can be found.

Usage of TFTP Client

The pseudo-code below shows the principal usage for reading a file.

int res;
ssize_t bytes;
void *tftp_handle;
tftp_net_config config;
const size_t buffer_size = 4000;
char data_buffer[buffer_size];
 
tftp_initialize_net_config( &config );
config.options.window_size = 1; // Set desired config values
 
res = tftp_open(
  "127.0.0.1",
  "filename.txt",
  true, // is_for_reading
  &config,
  &tftp_handle
);
 
if ( res != 0 || tftp_handle == NULL ) {
  // Error
}
 
// Use tftp_read() (probably in a loop) ...
bytes = tftp_read(
  tftp_handle,
  data_buffer,
  buffer_size
);
// ... or use tftp_write() instead when the file is open for writing.
 
res = tftp_close( tftp_handle );
 
if ( res != 0 ) {
  // Error ... check! Especially when writing!
}

Macro Definition Documentation

TFTP_RFC1350_WINDOW_SIZE

#define TFTP_RFC1350_WINDOW_SIZE   1

This window size avoids the sending of the windowsize option to the TFTP server.

This effectively mimics the operation defined in RFC 1350 which does not know any window size.

Typedef Documentation

tftp_net_config

typedef struct tftp_net_config tftp_net_config

This structure represents configuration value used by the TFTP client.

As defaults the values suggested in RFC 7440 are used.

tftp_options

typedef struct tftp_options tftp_options

This structure represents TFTP options negotiated between client and server.

RFC 2347 is the basis for the TFTP option.

Function Documentation

tftp_close()

int tftp_close

(

void *

tftp_handle

)

Close a TFTP client connection.

This directive sends all data which are still stored in a write buffer to the server (if any), tells the server that the connection ends (if required by RFC 1350) and releases any resources allocated at the client side.

Note

Especially, when writing a file to the server, the return code of tftp_close() should be checked. Invoking tftp_close() triggers the sending of the last – not completely filled – data block. This may fail the same way as any tftp_write() may fail. Therefore, an error returned by tftp_close() likely indicates that the file was not completely transferred.

Parameters

tftp_handle

is the reference returned by a call to tftp_open(). If this parameter is NULL, the directive call is a no-op.

Return values

0	When the client session was closed successfully.

Returns

Returns a POSIX errno value in case an error occurred.

tftp_initialize_net_config()

void tftp_initialize_net_config

(

tftp_net_config *

config

)

Set all members of a tftp_net_config structure to their default values.

Parameters

config

references a tftp_net_config structure. The values are set to the defaults defined in `type tftp_net_config`.

tftp_open()

int tftp_open	(	const char *	hostname,
		const char *	path,
		bool	is_for_reading,
		const tftp_net_config *	config,
		void **	tftp_handle
	)

Opens and starts a TFTP client session to read or write a single file.

This directive resolves the hostname or IP address, establishes a connection to the TFTP server and initiates the data transfer. It will not return before an error is encountered or the TFTP server has responded to the read or write request with a network packet.

TFTP uses timeouts (of unspecified length). It does not know keep-alive messages. If the client does not respond to the server in due time, the server sets the connection faulty and drops it. To avoid this the user of this code must read or write enough data fast enough.

"Enough data" means at least so much data which fills a single data packet or all packets of a window if windows are used. The data can be read or written in anything from one single large chunk to byte-by-byte pieces. The point is, one cannot pause the reading or writing for longer periods of time.

Parameters

	hostname	is the IPv4 address as string or the name of the TFTP server to connect to.
	path	is the pathname at the TFTP server side of the file to read or write. According to RFC 1350 the path must be in NETASCII. This is ASCII as defined in "USA Standard Code for Information Interchange" with the modifications specified in "Telnet Protocol Specification".
	is_for_reading	indicated whether the file is to be read or written. A value of true indicates that the file is intended to be read from the server. A value of false indicates that the file is to be written to the server.
	config	either references a structure defining the configuration values for this file transfer or is NULL. If it is NULL, default configuration values are used. See type tftp_net_config for a description and the defaults values. This function copies the data so that the memory pointed to by config can be used for other purposes after the call returns.
[out]	tftp_handle	references a place where a handle of the connection can be stored. On success a pointer to a handle is stored. On failure (return value other than 0) a NULL pointer is stored. This handle must be provided to all further calls to tftp_read(), tftp_write(), and tftp_close().

When this directive stores a non-NULL pointer in this place, a call to tftp_close() is mandatory to release allocated resources. This parameter cannot be NULL.

Return values

0	When the client session was opened successfully.

Returns

Returns a POSIX errno value in case an error occurred.

tftp_read()

ssize_t tftp_read	(	void *	tftp_handle,
		void *	buffer,
		size_t	count
	)

Read data from a TFTP server.

This directive attempts to read data from a TFTP connection open for reading.

Upon success, the buffer is always filled with count bytes of received data with the exception when the end of the file has been reached.

TFTP cannot recover from errors. Once an error is reported, the connection must be and can only be closed.

Parameters

	tftp_handle	is the reference returned by a call to tftp_open(). The file must be opened for reading.
[out]	buffer	references a memory area into which the received data is written.
	count	defines the size of the buffer in bytes.

Return values

0	The end of the file has been reached. There is no more data.

Returns

If greater or equal to 0, returns the number of bytes written into the buffer. If the return value is negative, an error occurred. In this case the negated value is a POSIX errno value.

tftp_write()

ssize_t tftp_write	(	void *	tftp_handle,
		const void *	buffer,
		size_t	count
	)

Write data to a TFTP server.

This directive attempts to write data to a TFTP connection open for writing.

On a successful call, all data in the buffer will be used. Yet, this does not imply that all data is actually sent. This depends on whether a whole data packet or window can be filled.

TFTP cannot recover from errors. Once an error is reported, the connection must be and can only be closed.

Parameters

tftp_handle	is the reference returned by a call to tftp_open(). The file must be opened for writing.
buffer	references a memory area which contains the data to be sent.
count	defines the size of the data in buffer in bytes.

Returns

If greater or equal to 0, returns the number of bytes used from the buffer. The value is always count on a successful call. If the return value is negative, an error occurred. In this case the negated value is a POSIX errno value.