VxWorks Reference Manual : Libraries
tftpLib - Trivial File Transfer Protocol (TFTP) client library
tftpXfer( ) - transfer a file via TFTP using a stream interface
tftpCopy( ) - transfer a file via TFTP
tftpInit( ) - initialize a TFTP session
tftpModeSet( ) - set the TFTP transfer mode
tftpPeerSet( ) - set the TFTP server address
tftpPut( ) - put a file to a remote system
tftpGet( ) - get a file from a remote system
tftpInfoShow( ) - get TFTP status information
tftpQuit( ) - quit a TFTP session
tftpSend( ) - send a TFTP message to the remote system
This library implements the VxWorks Trivial File Transfer Protocol (TFTP) client library. TFTP is a simple file transfer protocol (hence the name "trivial") implemented over UDP. TFTP was designed to be small and easy to implement; therefore it is limited in functionality in comparison with other file transfer protocols, such as FTP. TFTP provides only the read/write capability to and from a remote server.
TFTP provides no user authentication; therefore the remote files must have "loose" permissions before requests for file access will be granted by the remote TFTP server (i.e., files to be read must be publicly readable, and files to be written must exist and be publicly writeable). Some TFTP servers offer a secure option (-s) that specifies a directory where the TFTP server is rooted. Refer to the host manuals for more information about a particular TFTP server.
The tftpLib library has two levels of interface. The tasks tftpXfer( ) and tftpCopy( ) operate at the highest level and are the main call interfaces. The tftpXfer( ) routine provides a stream interface to TFTP. That is, it spawns a task to perform the TFTP transfer and provides a descriptor from which data can be transferred interactively. The tftpXfer( ) interface is similar to ftpXfer( ) in ftpLib. The tftpCopy( ) routine transfers a remote file to or from a passed file (descriptor).
The lower-level interface is made up of various routines that act on a TFTP session. Each TFTP session is defined by a TFTP descriptor. These routines include:
tftpInit( ) to initialize a session;
tftpModeSet( ) to set the transfer mode;
tftpPeerSet( ) to set a peer/server address;
tftpPut( ) to put a file to the remote system;
tftpGet( ) to get file from remote system;
tftpInfoShow( ) to show status information; and
tftpQuit( ) to quit a TFTP session.
The following code provides an example of how to use the lower-level routines. It implements roughly the same function as tftpCopy( ).
char * pHost; int port; char * pFilename; char * pCommand; char * pMode; int fd; TFTP_DESC * pTftpDesc; int status; if ((pTftpDesc = tftpInit ()) == NULL) return (ERROR); if ((tftpPeerSet (pTftpDesc, pHost, port) == ERROR) || (tftpModeSet (pTftpDesc, pMode) == ERROR)) { (void) tftpQuit (pTftpDesc); return (ERROR); } if (strcmp (pCommand, "get") == 0) { status = tftpGet (pTftpDesc, pFilename, fd, TFTP_CLIENT); } else if (strcmp (pCommand, "put") == 0) { status = tftpPut (pTftpDesc, pFilename, fd, TFTP_CLIENT); } else { errno = S_tftpLib_INVALID_COMMAND; status = ERROR; } (void) tftpQuit (pTftpDesc);
tftpLib.h
tftpdLib, VxWorks Programmer's Guide: Network
tftpXfer( ) - transfer a file via TFTP using a stream interface
STATUS tftpXfer ( char * pHost, /* host name or address */ int port, /* port number */ char * pFilename, /* remote filename */ char * pCommand, /* TFTP command */ char * pMode, /* TFTP transfer mode */ int * pDataDesc, /* return data desc. */ int * pErrorDesc /* return error desc. */ )
This routine initiates a transfer to or from a remote file via TFTP. It spawns a task to perform the TFTP transfer and returns a descriptor from which the data can be read (for "get") or to which it can be written (for "put") interactively. The interface for this routine is similar to ftpXfer( ) in ftpLib.
pHost is the server name or Internet address. A non-zero value for port specifies an alternate TFTP server port number (zero means use default TFTP port number (69)). pFilename is the remote filename. pCommand specifies the TFTP command. The command can be either "put" or "get".
The tftpXfer( ) routine returns a data descriptor, in pDataDesc, from which the TFTP data is read (for "get") or to which is it is written (for "put"). An error status descriptor gets returned in the variable pErrorDesc. If an error occurs during the TFTP transfer, an error string can be read from this descriptor. After returning successfully from tftpXfer( ), the calling application is responsible for closing both descriptors.
If there are delays in reading or writing the data descriptor, it is possible for the TFTP transfer to time out.
The following code demonstrates how tftpXfer( ) may be used:
#include "tftpLib.h" #define BUFFERSIZE 512 int dataFd; int errorFd; int num; char buf [BUFFERSIZE + 1]; if (tftpXfer ("congo", 0, "/usr/fred", "get", "ascii", &dataFd, &errorFd) == ERROR) return (ERROR); while ((num = read (dataFd, buf, sizeof (buf))) > 0) { .... } close (dataFd); num = read (errorFd, buf, BUFFERSIZE); if (num > 0) { buf [num] = '\0'; printf ("YIKES! An error occurred!:%s\n", buf); ..... } close (errorFd);
OK, or ERROR if unsuccessful.
S_tftpLib_INVALID_ARGUMENT
tftpCopy( ) - transfer a file via TFTP
STATUS tftpCopy ( char * pHost, /* host name or address */ int port, /* optional port number */ char * pFilename, /* remote filename */ char * pCommand, /* TFTP command */ char * pMode, /* TFTP transfer mode */ int fd /* fd to put/get data */ )
This routine transfers a file using the TFTP protocol to or from a remote system. pHost is the remote server name or Internet address. A non-zero value for port specifies an alternate TFTP server port (zero means use default TFTP port number (69)). pFilename is the remote filename. pCommand specifies the TFTP command, which can be either "put" or "get". pMode specifies the mode of transfer, which can be "ascii", "netascii", "binary", "image", or "octet".
fd is a file descriptor from which to read/write the data from or to the remote system. For example, if the command is "get", the remote data will be written to fd. If the command is "put", the data to be sent is read from fd. The caller is responsible for managing fd. That is, fd must be opened prior to calling tftpCopy( ) and closed up on completion.
The following sequence gets an ASCII file "/folk/vw/xx.yy" on host "congo" and stores it to a local file called "localfile":
-> fd = open ("localfile", 0x201, 0644) -> tftpCopy ("congo", 0, "/folk/vw/xx.yy", "get", "ascii", fd) -> close (fd)
OK, or ERROR if unsuccessful.
S_tftpLib_INVALID_COMMAND
tftpInit( ) - initialize a TFTP session
TFTP_DESC * tftpInit (void)
This routine initializes a TFTP session by allocating and initializing a TFTP descriptor. It sets the default transfer mode to "netascii".
A pointer to a TFTP descriptor if successful, otherwise NULL.
tftpModeSet( ) - set the TFTP transfer mode
STATUS tftpModeSet ( TFTP_DESC * pTftpDesc, /* TFTP descriptor */ char * pMode /* TFTP transfer mode */ )
This routine sets the transfer mode associated with the TFTP descriptor pTftpDesc. pMode specifies the transfer mode, which can be "netascii", "binary", "image", or "octet". Although recognized, these modes actually translate into either octet or netascii.
OK, or ERROR if unsuccessful.
S_tftpLib_INVALID_DESCRIPTOR
S_tftpLib_INVALID_ARGUMENT
S_tftpLib_INVALID_MODE
tftpPeerSet( ) - set the TFTP server address
STATUS tftpPeerSet ( TFTP_DESC * pTftpDesc, /* TFTP descriptor */ char * pHostname, /* server name/address */ int port /* port number */ )
This routine sets the TFTP server (peer) address associated with the TFTP descriptor pTftpDesc. pHostname is either the TFTP server name (e.g., "congo") or the server Internet address (e.g., "90.3"). A non-zero value for port specifies the server port number (zero means use the default TFTP server port number (69)).
OK, or ERROR if unsuccessful.
S_tftpLib_INVALID_DESCRIPTOR
S_tftpLib_INVALID_ARGUMENT
S_tftpLib_UNKNOWN_HOST
tftpPut( ) - put a file to a remote system
STATUS tftpPut ( TFTP_DESC * pTftpDesc, /* TFTP descriptor */ char * pFilename, /* remote filename */ int fd, /* file descriptor */ int clientOrServer /* which side is calling */ )
This routine puts data from a local file (descriptor) to a file on the remote system. pTftpDesc is a pointer to the TFTP descriptor. pFilename is the remote filename. fd is the file descriptor from which it gets the data. A call to tftpPeerSet( ) must be made prior to calling this routine.
OK, or ERROR if unsuccessful.
S_tftpLib_INVALID_DESCRIPTOR
S_tftpLib_INVALID_ARGUMENT
S_tftpLib_NOT_CONNECTED
tftpGet( ) - get a file from a remote system
STATUS tftpGet ( TFTP_DESC * pTftpDesc, /* TFTP descriptor */ char * pFilename, /* remote filename */ int fd, /* file descriptor */ int clientOrServer /* which side is calling */ )
This routine gets a file from a remote system via TFTP. pFilename is the filename. fd is the file descriptor to which the data is written. pTftpDesc is a pointer to the TFTP descriptor. The tftpPeerSet( ) routine must be called prior to calling this routine.
OK, or ERROR if unsuccessful.
S_tftpLib_INVALID_DESCRIPTOR
S_tftpLib_INVALID_ARGUMENT
S_tftpLib_NOT_CONNECTED
tftpInfoShow( ) - get TFTP status information
STATUS tftpInfoShow ( TFTP_DESC * pTftpDesc /* TFTP descriptor */ )
This routine prints information associated with TFTP descriptor pTftpDesc.
A call to tftpInfoShow( ) might look like:
-> tftpInfoShow (tftpDesc) Connected to yuba [69] Mode: netascii Verbose: off Tracing: off Rexmt-interval: 5 seconds, Max-timeout: 25 seconds value = 0 = 0x0 ->
OK, or ERROR if unsuccessful.
S_tftpLib_INVALID_DESCRIPTOR
tftpQuit( ) - quit a TFTP session
STATUS tftpQuit ( TFTP_DESC * pTftpDesc /* TFTP descriptor */ )
This routine closes a TFTP session associated with the TFTP descriptor pTftpDesc.
OK, or ERROR if unsuccessful.
S_tftpLib_INVALID_DESCRIPTOR
tftpSend( ) - send a TFTP message to the remote system
int tftpSend ( TFTP_DESC * pTftpDesc, /* TFTP descriptor */ TFTP_MSG * pTftpMsg, /* TFTP send message */ int sizeMsg, /* send message size */ TFTP_MSG * pTftpReply, /* TFTP reply message */ int opReply, /* reply opcode */ int blockReply, /* reply block number */ int * pPort /* return port number */ )
This routine sends sizeMsg bytes of the passed message pTftpMsg to the remote system associated with the TFTP descriptor pTftpDesc. If pTftpReply is not NULL, tftpSend( ) tries to get a reply message with a block number blockReply and an opcode opReply. If pPort is NULL, the reply message must come from the same port to which the message was sent. If pPort is not NULL, the port number from which the reply message comes is copied to this variable.
The size of the reply message, or ERROR.
S_tftpLib_TIMED_OUT
S_tftpLib_TFTP_ERROR