VxWorks API Reference : OS Libraries
ftpLib - File Transfer Protocol (FTP) library
ftpCommand( ) - send an FTP command and get the reply
ftpCommandEnhanced( ) - send an FTP command and get the complete RFC reply code
ftpXfer( ) - initiate a transfer via FTP
ftpReplyGet( ) - get an FTP command reply
ftpReplyGetEnhanced( ) - get an FTP command reply
ftpHookup( ) - get a control connection to the FTP server on a specified host
ftpLogin( ) - log in to a remote FTP server
ftpDataConnInitPassiveMode( ) - initialize an FTP data connection using PASV mode
ftpDataConnInit( ) - initialize an FTP data connection using PORT mode
ftpDataConnGet( ) - get a completed FTP data connection
ftpLs( ) - list directory contents via FTP
ftpLibDebugOptionSet( ) - set the debug level of the ftp library routines
ftpTransientConfigSet( ) - set parameters for host FTP_TRANSIENT responses
ftpTransientConfigGet( ) - get parameters for host FTP_TRANSIENT responses
ftpTransientFatalInstall( ) - set applette to stop FTP transient host responses
This library provides facilities for transferring files to and from a host via File Transfer Protocol (FTP). This library implements only the "client" side of the FTP facilities.
For most purposes, you should access the services of ftpLib by means of netDrv, a VxWorks I/O driver that supports transparent access to remote files by means of standard I/O system calls. Before attempting to access ftpLib services directly, you should check whether netDrv already provides the same access for less trouble.
The routines ftpXfer( ) and ftpReplyGet( ) provide the highest level of direct interface to FTP. The routine ftpXfer( ) connects to a specified remote FTP server, logs in under a specified user name, and initiates a specified data transfer command. The routine ftpReplyGet( ) receives control reply messages sent by the remote FTP server in response to the commands sent.
The routines ftpHookup( ), ftpLogin( ), ftpDataConnInit( ), ftpDataConnGet( ), ftpCommand( ), ftpCommandEnhanced( ) provide the primitives necessary to create and use control and data connections to remote FTP servers. The following example shows how to use these low-level routines. It implements roughly the same function as ftpXfer( ).
char *host, *user, *passwd, *acct, *dirname, *filename; int ctrlSock = ERROR; /* This is the control socket file descriptor */ int dataSock = ERROR; /* This is the data path socket file descriptor */ if (((ctrlSock = ftpHookup (host)) == ERROR) || (ftpLogin (ctrlSock, user, passwd, acct) == ERROR) || (ftpCommand (ctrlSock, "TYPE I", 0, 0, 0, 0, 0, 0) != FTP_COMPLETE) || (ftpCommand (ctrlSock, "CWD %s", dirname, 0, 0, 0, 0, 0) != FTP_COMPLETE) || ((dataSock = ftpDataConnInit (ctrlSock)) == ERROR) || (ftpCommand (ctrlSock, "RETR %s", filename, 0, 0, 0, 0, 0) != FTP_PRELIM) || ((dataSock = ftpDataConnGet (dataSock)) == ERROR)) { /* an error occurred; close any open sockets and return */ if (ctrlSock != ERROR) close (ctrlSock); if (dataSock != ERROR) close (dataSock); return (ERROR); }For even lower-level access, please note that the sockets provided by ftpHookup( ) and ftpDataConnInit( ) are standard TCP/IP sockets. Developers may implement read( ), write( ) and select( ) calls using these sockets for maximum flexibility.To use this feature, include the following component: INCLUDE_FTP
Please note that accessing multiple files simultaneously may require increasing the memory available to the network stack. You can examine memory requirements by using netStackSysPoolShow( ) and netStackDataPoolShow( ) before opening and after closing files.
You may need to modify the following macro definitions according to your specific memory requirements:
NUM_64
NUM_128
NUM_256
NUM_512
NUM_1024
NUM_2048
NUM_SYS_64
NUM_SYS_128
NUM_SYS_256
NUM_SYS_512
NUM_SYS_1024
NUM_SYS_2048Please also note that each concurrent file access requires three file descriptors (File, Control and Socket). The following macro definition may need modification per your application: NUM_FILES
Developers are encouraged to enable the error reporting facility during debugging using the function ftpLibDebugOptionsSet( ). The output is displayed via the logging facility.
ftpLib.h
ftpCommand( ) - send an FTP command and get the reply
int ftpCommand ( int ctrlSock, /* fd of control connection socket */ char * fmt, /* format string of command to send */ int arg1, /* first of six args to format string */ int arg2, int arg3, int arg4, int arg5, int arg6 )
This command has been superceded by ftpCommandEnhanced( )
This routine sends the specified command on the specified socket, which should be a control connection to a remote FTP server. The command is specified as a string in printf( ) format with up to six arguments.
After the command is sent, ftpCommand( ) waits for the reply from the remote server. The FTP reply code is returned in the same way as in ftpReplyGet( ).
ftpCommand (ctrlSock, "TYPE I", 0, 0, 0, 0, 0, 0); /* image-type xfer */ ftpCommand (ctrlSock, "STOR %s", file, 0, 0, 0, 0, 0); /* init file write */
1 = FTP_PRELIM (positive preliminary)
2 = FTP_COMPLETE (positive completion)
3 = FTP_CONTINUE (positive intermediate)
4 = FTP_TRANSIENT (transient negative completion)
5 = FTP_ERROR (permanent negative completion)ERROR if there is a read/write error or an unexpected EOF.
ftpLib, ftpReplyGet( )
VARARGS2
ftpCommandEnhanced( ) - send an FTP command and get the complete RFC reply code
int ftpCommandEnhanced ( int ctrlSock, /* fd of control connection socket */ char * fmt, /* format string of command to send */ int arg1, /* first of six args to format string */ int arg2, int arg3, int arg4, int arg5, int arg6, char * replyString, /* storage for the last line of the server */ /* response or NULL */ int replyStringLength /* Maximum character length of the replyString */ )
This command supercedes ftpCommand( )
This routine sends the specified command on the specified socket, which should be a control connection to a remote FTP server. The command is specified as a string in printf( ) format with up to six arguments.
After the command is sent, ftpCommand( ) waits for the reply from the remote server. The FTP reply code is returned in the same way as in ftpReplyGetEnhanced( ).
ftpCommandEnhanced (ctrlSock, "TYPE I", 0, 0, 0, 0, 0, 0, 0, 0); /* image-type xfer */ ftpCommandEnhanced (ctrlSock, "STOR %s", file, 0, 0, 0, 0, 0, 0, 0); /* init file write */ ftpCommandEnhanced (ctrlSock, "PASV", file, 0, 0, 0, 0, 0, reply, rplyLen); /* Get port */
The complete FTP response code (see RFC #959)
ERROR if there is a read/write error or an unexpected EOF.
ftpLib, ftpReplyGetEnhanced( ), ftpReplyGet( )
VARARGS2
ftpXfer( ) - initiate a transfer via FTP
STATUS ftpXfer ( char * host, /* name of server host */ char * user, /* user name for host login */ char * passwd, /* password for host login */ char * acct, /* account for host login */ char * cmd, /* command to send to host */ char * dirname, /* directory to cd to before sending command */ char * filename, /* filename to send with command */ int * pCtrlSock, /* where to return control socket fd */ int * pDataSock /* where to return data socket fd, (NULL == */ /* don't open data connection) */ )
This routine initiates a transfer via a remote FTP server in the following order:
The resulting control and data connection file descriptors are returned via pCtrlSock and pDataSock, respectively.
(1) Establishes a connection to the FTP server on the specified host. (2) Logs in with the specified user name, password, and account, as necessary for the particular host. (3) Sets the transfer type to image by sending the command "TYPE I". (4) Changes to the specified directory by sending the command "CWD dirname". (5) Sends the specified transfer command with the specified filename as an argument, and establishes a data connection. Typical transfer commands are "STOR %s", to write to a remote file, or "RETR %s", to read a remote file. After calling this routine, the data can be read or written to the remote server by reading or writing on the file descriptor returned in pDataSock. When all incoming data has been read (as indicated by an EOF when reading the data socket) and/or all outgoing data has been written, the data socket fd should be closed. The routine ftpReplyGet( ) should then be called to receive the final reply on the control socket, after which the control socket should be closed.
If the FTP command does not involve data transfer, pDataSock should be NULL, in which case no data connection will be established. The only FTP commands supported for this case are DELE, RMD, and MKD.
The following code fragment reads the file "/usr/fred/myfile" from the host "server", logged in as user "fred", with password "magic" and no account name.
#include "vxWorks.h" #include "ftpLib.h" int ctrlSock; int dataSock; char buf [512]; int nBytes; STATUS status; if (ftpXfer ("server", "fred", "magic", "", "RETR %s", "/usr/fred", "myfile", &ctrlSock, &dataSock) == ERROR) return (ERROR); while ((nBytes = read (dataSock, buf, sizeof (buf))) > 0) { ... } close (dataSock); if (nBytes < 0) /* read error? */ status = ERROR; if (ftpReplyGet (ctrlSock, TRUE) != FTP_COMPLETE) status = ERROR; if (ftpCommand (ctrlSock, "QUIT", 0, 0, 0, 0, 0, 0) != FTP_COMPLETE) status = ERROR; close (ctrlSock);
OK, or ERROR if any socket cannot be created or if a connection cannot be made.
ftpLib, ftpReplyGet( )
ftpReplyGet( ) - get an FTP command reply
int ftpReplyGet ( int ctrlSock, /* control socket fd of FTP connection */ BOOL expecteof /* TRUE = EOF expected, FALSE = EOF is error */ )
This routine has been superceded by ftpReplyGetEnhanced( )
This routine gets a command reply on the specified control socket.
The three-digit reply code from the first line is saved and interpreted. The left-most digit of the reply code identifies the type of code (see RETURNS below).
The caller's error status is always set to the complete three-digit reply code regardless of the actual reply value (see the manual entry for errnoGet( )). If the reply code indicates an error, the entire reply is printed if the ftp error printing is enabled (see the manual entry for ftpLibDebugOptionsSet( )).
If an EOF is encountered on the specified control socket, but no EOF was expected (expecteof == FALSE), then ERROR is returned.
1 = FTP_PRELIM (positive preliminary)
2 = FTP_COMPLETE (positive completion)
3 = FTP_CONTINUE (positive intermediate)
4 = FTP_TRANSIENT (transient negative completion)
5 = FTP_ERROR (permanent negative completion)ERROR if there is a read/write error or an unexpected EOF.
ftpReplyGetEnhanced( ) - get an FTP command reply
int ftpReplyGetEnhanced ( int ctrlSock, /* control socket fd of FTP connection */ BOOL expecteof, /* TRUE = EOF expected, FALSE = EOF is error */ char * replyString, /* Location to store text of reply, or NULL */ int stringLengthMax /* Maximum length of reply (not including NULL) */ )
This routine supercedes ftpReplyGet( )
This routine gets a command reply on the specified control socket.
The three-digit reply code from the first line is saved and interpreted. The left-most digit of the reply code identifies the type of code (see RETURNS below).
The caller's error status is always set to the complete three-digit reply code (see the manual entry for errnoGet( )). If the reply code indicates an error, the entire reply is printed if the ftp error printing is enabled (see the manual entry for ftpLibDebugOptionsSet( )).
The last line of text retrieved from the servers response is stored in the location specified by replyString. If replyString is NULL the parameter is ignored.
If an EOF is encountered on the specified control socket, but no EOF was expected (expecteof == FALSE), then ERROR is returned.
The complete FTP response code (see RFC #959)
ERROR if there is a read/write error or an unexpected EOF.
ftpHookup( ) - get a control connection to the FTP server on a specified host
int ftpHookup ( char * host /* server host name or inet address */ )
This routine establishes a control connection to the FTP server on the specified host. This is the first step in interacting with a remote FTP server at the lowest level. (For a higher-level interaction with a remote FTP server, see the manual entry for ftpXfer( ).)
The file descriptor of the control socket, or ERROR if the Internet address or the host name is invalid, if a socket could not be created, or if a connection could not be made.
ftpLib, ftpLogin( ), ftpXfer( )
ftpLogin( ) - log in to a remote FTP server
STATUS ftpLogin ( int ctrlSock, /* fd of login control socket */ char * user, /* user name for host login */ char * passwd, /* password for host login */ char * account /* account for host login */ )
This routine logs in to a remote server with the specified user name, password, and account name, as required by the specific remote host. This is typically the next step after calling ftpHookup( ) in interacting with a remote FTP server at the lowest level. (For a higher-level interaction with a remote FTP server, see the manual entry for ftpXfer( )).
OK, or ERROR if the routine is unable to log in.
ftpLib, ftpHookup( ), ftpXfer( )
ftpDataConnInitPassiveMode( ) - initialize an FTP data connection using PASV mode
int ftpDataConnInitPassiveMode ( int ctrlSock /* fd of associated control socket */ )
This routine sets up the client side of a data connection for the specified control connection. It issues a PASV command and attempts to connect to the host-specified port. If the host responds that it can not process the PASV command (command not supported) or fails to recognize the command, it will return ERROR.
This routine must be called before the data-transfer command is sent; otherwise, the server's connect may fail.
This routine is called after ftpHookup( ) and ftpLogin( ) to establish a connection with a remote FTP server a low level. (For a higher-level interaction with a remote FTP server, see ftpXfer( ).)
This function is preferred over ftpDataConnInit( ) because the remote system must preserve old port connection pairs even if the target system suffers from a reboot (2MSL). Using PASV we encourage the host's selection of a fresh port.
The file descriptor of the data socket created, or ERROR.
ftpLib, ftpHookup( ), ftpLogin( ), ftpCommandEnhanced( ), ftpXfer( ), ftpConnInit( )
ftpDataConnInit( ) - initialize an FTP data connection using PORT mode
int ftpDataConnInit ( int ctrlSock /* fd of associated control socket */ )
This routine sets up the client side of a data connection for the specified control connection using the PORT command. It creates the data port, informs the remote FTP server of the data port address, and listens on that data port. The server will then connect to this data port in response to a subsequent data-transfer command sent on the control connection (see the manual entry for ftpCommand( )).
This routine must be called before the data-transfer command is sent; otherwise, the server's connect may fail.
This routine is called after ftpHookup( ) and ftpLogin( ) to establish a connection with a remote FTP server at the lowest level. (For a higher-level interaction with a remote FTP server, see ftpXfer( ).)
Please note that ftpDataConnInitPassiveMode( ) is recommended instead of ftpDataConnInit( ).
The file descriptor of the data socket created, or ERROR.
ftpLib, ftpDataConnInitPassiveMode( ), ftpHookup( ), ftpLogin( ), ftpCommand( ), ftpXfer( )
ftpDataConnGet( ) - get a completed FTP data connection
int ftpDataConnGet ( int dataSock /* fd of data socket on which to await */ /* connection */ )
This routine completes a data connection initiated by a call to ftpDataConnInit( ). It waits for a connection on the specified socket from the remote FTP server. The specified socket should be the one returned by ftpDataConnInit( ). The connection is established on a new socket, whose file descriptor is returned as the result of this function. The original socket, specified in the argument to this routine, is closed.
Usually this routine is called after ftpDataConnInit( ) and ftpCommand( ) to initiate a data transfer from/to the remote FTP server.
The file descriptor of the new data socket, or ERROR if the connection failed.
ftpLib, ftpDataConnInit( ), ftpCommand( )
ftpLs( ) - list directory contents via FTP
STATUS ftpLs ( char * dirName /* name of directory to list */ )
This routine lists the contents of a directory. The content list is obtained via an NLST FTP transaction.
The local device name must be the same as the remote host name with a colon ":" as a suffix. (For example "wrs:" is the device name for the "wrs" host.)
OK, or ERROR if could not open directory.
ftpLibDebugOptionSet( ) - set the debug level of the ftp library routines
void ftpLibDebugOptionsSet ( UINT32 debugLevel )
This routine enables the debugging of ftp transactions using the ftp library.
Debugging Level Meaning FTPL_DEBUG_OFF No debugging messages. FTPL_DEBUG_INCOMING Display all incoming responses. FTPL_DEBUG_OUTGOING Display all outgoing commands. FTPL_DEBUG_ERRORS Display warnings and errors
ftpLibDebugOptionsSet (FTPL_DEBUG_ERRORS); /* Display any runtime errors */ ftpLibDebugOptionsSet (FTPL_DEBUG_OUTGOING); /* Display outgoing commands */ ftpLibDebugOptionsSet (FTPL_DEBUG_INCOMING); /* Display incoming replies */ ftpLibDebugOptionsSet (FTPL_DEBUG_INCOMING | /* Display both commands and */ FTPL_DEBUG_OUTGOING); /* replies */
ftpTransientConfigSet( ) - set parameters for host FTP_TRANSIENT responses
STATUS ftpTransientConfigSet ( UINT32 maxRetryCount, /* The maximum number of attempts to retry */ UINT32 retryInterval /* time (in system clock ticks) between retries */ )
This routine adjusts the delay between retries in response to receiving FTP_PRELIM and the maximum retry count permitted before failing.
OK
ftpTransientConfigGet( ) - get parameters for host FTP_TRANSIENT responses
STATUS ftpTransientConfigGet ( UINT32 * maxRetryCount, /* The maximum number of attempts to retry */ UINT32 * retryInterval /* time (in system clock ticks) between retries */ )
This routine retrieves the delay between retries in response to receiving FTP_TRANSIENT and the maximum retry count permitted before failing.
OK
ftpLib, ftpTransientConfigSet, tickLib
ftpTransientFatalInstall( ) - set applette to stop FTP transient host responses
STATUS ftpTransientFatalInstall ( FUNCPTR pApplette /* function that returns TRUE or FALSE */ )
The routine installs a function which will determine if a transient response should be fatal. Some ftp servers incorrectly use transient responses instead of error to describe conditions such as disk full.
OK if the installation is successful, or ERROR if the installation fails.
ftpLib, ftpTransientConfigSet( ), ftpTransientFatal( ) in target/config/comps/src/net/usrFtp.c