RTEMS 6.1-rc2
Loading...
Searching...
No Matches
Data Structures | Macros | Typedefs | Functions
Trivial File Transfer Protocol (TFTP) API
API » IO

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

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;
const size_t buffer_size = 4000;
char data_buffer[buffer_size];
config.options.window_size = 1; // Set desired config values
res = tftp_open(
"127.0.0.1",
"filename.txt",
true, // is_for_reading
&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!
}
int tftp_close(void *tftp_handle)
Close a TFTP client connection.
Definition: tftpDriver.c:1430
void tftp_initialize_net_config(tftp_net_config *config)
Set all members of a tftp_net_config structure to their default values.
Definition: tftpDriver.c:1237
ssize_t tftp_read(void *tftp_handle, void *buffer, size_t count)
Read data from a TFTP server.
Definition: tftpDriver.c:1316
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.
Definition: tftpDriver.c:1255
#define NULL
Requests a GPIO pin group configuration.
Definition: xil_types.h:54
Definition: deflate.c:114
This structure represents configuration value used by the TFTP client.
Definition: tftp.h:213

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

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_handleis the reference returned by a call to tftp_open(). If this parameter is NULL, the directive call is a no-op.
Return values
0When 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
configreferences 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
hostnameis the IPv4 address as string or the name of the TFTP server to connect to.
pathis 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_readingindicated 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.
configeither 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_handlereferences 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
0When 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_handleis the reference returned by a call to tftp_open(). The file must be opened for reading.
[out]bufferreferences a memory area into which the received data is written.
countdefines the size of the buffer in bytes.
Return values
0The 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_handleis the reference returned by a call to tftp_open(). The file must be opened for writing.
bufferreferences a memory area which contains the data to be sent.
countdefines 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.