VxWorks Reference Manual : Libraries
ftpLib - File Transfer Protocol (FTP) library
ftpCommand( ) - send an FTP command and get the reply
ftpXfer( ) - initiate a transfer via FTP
ftpReplyGet( ) - 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
ftpDataConnInit( ) - initialize an FTP data connection
ftpDataConnGet( ) - get a completed FTP data connection
ftpLs( ) - list directory contents via FTP
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.
VxWorks provides an I/O driver, netDrv, that allows transparent access to remote files via standard I/O system calls. The FTP facilities of ftpLib are primarily used by netDrv to access remote files. Thus for most purposes, it is not necessary to be familiar with ftpLib.
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( ), and ftpCommand( ) 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; int dataSock = ERROR; 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); }
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 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
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 */ /* connection) */ )
This routine initiates a transfer via a remote FTP server in the following order:
- (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.
The resulting control and data connection file descriptors are returned via pCtrlSock and pDataSock, respectively.
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 gets a command reply on the specified control socket. All the lines of a reply are read (multi-line replies are indicated with the continuation character "-" as the fourth character of all but the last line).
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 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 on standard error.
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.
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( )
ftpDataConnInit( ) - initialize an FTP data connection
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. 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( ).)
The file descriptor of the data socket created, or ERROR.
ftpLib, 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.