ftp_xfer(3N) TCP/IP 5.4R3.00 ftp_xfer(3N)
NAME
ftpxfer, ftpdir, ftpdel, ftpmkdir, ftprename, ftprmdir,
ftperror - implement the programmable interface to the File Transfer
Protocol
SYNOPSIS
#include <arpa/pftp.h>
void ftpxfer (char *username, char *password, char *hostname, char
*locpath, char *rempath, int *code);
void ftpdir (char *username, char *password, char *hostname, char
*rempath, char *locbuff, int *bufsize, int *code);
void ftpdel (char *username, char *password, char *hostname, char
*rempath, int *code);
void ftpmkdir (char *username, char *password, char *hostname, char
*rempath, int *code);
void ftprename (char *username, char *password, char *hostname, char
*frompath, char *topath, int *code);
void ftprmdir (char *username, char *password, char *hostname, char
*rempath, int *code);
void ftperror (int *errcode, char *errstr, int *errlen);
where:
username A string containing the username for login on hostname.
The maximum length is specified by FTP_USERNAME_LEN.
password A string containing the password for login on hostname. If
the account does not require a password, this should be a
pointer to a NULL string. The maximum length is specified
by FTP_PASSWORD_LEN.
hostname A string containing the remote hostname to access. The
maximum length is specified by FTP_HOSTNAME_LEN.
locpath A string containing the filename (pathname) of the file to
access on the local host. The maximum length is specified
by FTP_LOC_PATH_LEN.
rempath A string containing the filename (pathname) of the file to
access on the remote host. The maximum length is specified
by FTP_REM_PATH_LEN.
code A pointer to an integer specifying transfer modes and
optional behavior for the function call. On return, code
contains a result code from the specified operation.
locbuff A user-supplied buffer to receive the text information
returned by the FTP dir command.
bufsize A pointer to an integer containing the size of locbuff
initially, and the number of characters returned in
locbuff on completion.
frompath A string containing the filename (pathname) of the file to
be renamed on the remote host.
topath A string containing the new filename (pathname) of the file
being renamed on the remote host.
errcode A pointer to an integer containing an error number to be
mapped to an error string.
errstr A user-supplied buffer to receive the text information
describing the error specified by errcode.
errlen A pointer to an integer that returns the number of
characters in errstr.
Licensed material--property of copyright holder(s) 1
ftp_xfer(3N) TCP/IP 5.4R3.00 ftp_xfer(3N)
DESCRIPTION
This set of library routines implement the programmable interface to
the File Transfer Protocol (FTP) application.
ftpxfer transfers a file between the local host and the host
specified in hostname. FTP logs in to hostname using username and
password. File transfer occurs between locpath and rempath. The
transfer direction, mode, structure, and type must be specified in
code. Command completion status is returned in code.
ftpdir returns in locbuff the output from the FTP dir command. FTP
logs in to hostname using username and password. rempath specifies
the remote directory to list on hostname. locbuff is written with
the output of the FTP dir command and is not null-terminated. If the
output is smaller than bufsize, locbuff is padded with spaces. If
the output is larger than bufsize, the call will fail with an
FTP_ERR_OVERFLOW error. Upon completion, bufsize contains the
number of output characters (excluding the space padding) returned in
locbuff. Command completion status is returned in code.
ftpdel deletes the file specified in rempath on the remote host
hostname. FTP logs in to hostname using username and password.
rempath specifies the remote file to delete. Command completion
status is returned in code.
ftpmkdir creates the directory specified in rempath on the remote
host hostname. FTP logs in to hostname using username and password.
rempath specifies the remote directory to create. ftpmkdir will
fail if rempath already exists. Command completion status is
returned in code.
ftprename renames the file specified in frompath on the remote host
hostname to the file specified in topath. FTP logs in to hostname
using username and password. If topath exists, it will be
overwritten. Command completion status is returned in code.
ftprmdir deletes the directory specified in rempath on the remote
host hostname. FTP logs in to hostname using username and password.
Command completion status is returned in code.
ftperror maps an error number specified in errcode to an error
message string. errstr is returned as a non-null-terminated string
that is padded with spaces to FTP_MAXERRSTR_LEN length. errlen
contains the error message string length.
Transfer Modes and Optional Behavior
In each function that specifies code, code is constructed by or-ing
the flags specified below. If no options are required, code must
point to an integer initialized to zero.
FTP_DEBUG Enable debugging. This option logs FTP client/server
transactions to /tmp/pftp<processID>. (Note that this
is not the same as the FTP debug command.) The output
produced by selecting FTP_DEBUG is similar to the text
Licensed material--property of copyright holder(s) 2
ftp_xfer(3N) TCP/IP 5.4R3.00 ftp_xfer(3N)
generated during an interactive ftp(1C) session. This
option applies to all interfaces described in this man
page which specify code.
The remaining flags apply only to ftpxfer().
One of the following file transfer directions is required by
ftpxfer():
FTP_GET_OP Retrieve the rempath file from hostname into locpath on
the local host.
FTP_PUT_OP Store the locpath file on the local host into rempath
on hostname.
One of the following file transfer modes is required by ftpxfer():
FTP_STREAM_MODE Transfer the file using FTP's STREAM mode.
FTP_BLOCK_MODE Transfer the file using FTP's BLOCK mode.
FTP_COMPRESS_MODE Transfer the file using FTP's COMPRESS mode.
One of the following file transfer structures is required by
ftpxfer():
FTP_FILE_STRUCT Transfer the file using FTP's FILE structure.
FTP_PAGE_STRUCT Transfer the file using FTP's PAGE structure.
FTP_RECORD_STRUCT Transfer the file using FTP's RECORD structure.
One of the following file transfer types is required by ftpxfer():
FTP_ASCII_NONPRINT_TYPE Transfer the file using FTP's ASCII NON-
PRINT type.
FTP_ASCII_TELNET_TYPE Transfer the file using FTP's ASCII TELNET
type.
FTP_ASCII_CC_TYPE Transfer the file using FTP's ASCII
CARRIAGE_CONTROL type.
FTP_EBCDIC_NONPRINT_TYPE Transfer the file using FTP's EBCDIC NON-
PRINT type.
FTP_EBCDIC_TELNET_TYPE Transfer the file using FTP's EBCDIC TELNET
type.
FTP_EBCDIC_CC_TYPE Transfer the file using FTP's EBCDIC
CARRIAGE_CONTROL type.
FTP_BINARY_TYPE Transfer the file using FTP's BINARY type.
Licensed material--property of copyright holder(s) 3
ftp_xfer(3N) TCP/IP 5.4R3.00 ftp_xfer(3N)
FTP_IMAGE_TYPE Transfer the file using FTP's IMAGE type.
(Same as FTP_BINARY_TYPE)
Either of the following file transfer options can be used with
ftpxfer():
FTP_OVERWRITE Overwrite the destination file with the source file.
If the destination file does not exist, it will be
created.
FTP_APPEND Append the source file to the destination file. If
the destination file does not exist, it is created.
FTP_APPEND is invalid with FTP_GET_OP.
EPC FORTRAN 77 Interface
The FTP programmable interface also supports calls from Edinburgh
Portable Compiler's FORTRAN 77 language. A sample FORTRAN fragment
is shown below:
C
PROGRAM F77FTP
C
#include "arpa/pftp.h"
C
CHARACTER*FTPUSERNAMELEN USERNAME
CHARACTER*FTPPASSWORDLEN PASSWORD
CHARACTER*FTPHOSTNAMELEN HOSTNAME
CHARACTER*FTPLOCPATHLEN LOCPATHNAME
CHARACTER*FTPREMPATHLEN REMPATHNAME
INTEGER CODE
CHARACTER*2048 BUFF
CHARACTER*FTPMAXERRSTRLEN ERRSTR
INTEGER BUFSIZE
CHARACTER*FTPLOCPATHLEN OLDPATHNAME
CHARACTER*FTPREMPATHLEN NEWPATHNAME
C
CALL FTPXFER(USERNAME,PASSWORD,HOSTNAME,
& LOCPATHNAME,REMPATHNAME,CODE)
C
CALL FTPRENAME(USERNAME,PASSWORD,HOSTNAME,
& OLDPATHNAME,NEWPATHNAME,CODE)
C
CALL FTPMKDIR(USERNAME,PASSWORD,HOSTNAME,REMPATHNAME,CODE)
C
CALL FTPDIR(USERNAME,PASSWORD,HOSTNAME,REMPATHNAME,
& BUFF,BUFSIZE,CODE)
C
CALL FTPDEL(USERNAME,PASSWORD,HOSTNAME,REMPATHNAME,CODE)
C
CALL FTPRMDIR(USERNAME,PASSWORD,HOSTNAME,REMPATHNAME,CODE)
C
CALL FTPERROR(CODE,ERRSTR,BUFSIZE)
C
END
Licensed material--property of copyright holder(s) 4
ftp_xfer(3N) TCP/IP 5.4R3.00 ftp_xfer(3N)
DIAGNOSTICS
On return, code may be set to one of the following:
FTP_ERR_INVALID Unable to detect FTP server reply code.
FTP_NO_ERROR No error; the operation was successful.
FTP_ERR_READ_TIMEOUT Timeout occurred during reply read() from
FTP server.
FTP_ERR_WRITE_TIMEOUT Timeout occurred during command write() to
FTP server.
FTP_ERR_BAD_REPLY FTP server failed to return expected reply
code.
FTP_ERR_CONNECT_FAILED Failed to receive FTP server prompt.
FTP_ERR_LOGON_FAILED Login failure on FTP server.
FTP_ERR_BAD_LOC_PATH Unable to access local file during FTP get
operation.
FTP_ERR_BAD_REM_PATH Unable to access remote file during FTP put
operation.
FTP_ERR_NO_REM_PATH Unable to access remote file during FTP get
operation.
FTP_ERR_NO_LOC_PATH Unable to access local file during FTP put
operation.
FTP_ERR_LOC_PATH_EXISTS Attempt to overwrite an existing local file
without specifying FTP_OVERWRITE.
FTP_ERR_REM_PATH_EXISTS Attempt to overwrite an existing remote
file without specifying FTP_OVERWRITE.
FTP_ERR_UNSUPPORTED_OP Attempted to perform FTP_GET_OP with
FTP_APPEND.
FTP_ERR_TYPE_OPTIONS Multiple transfer types specified.
FTP_ERR_STRUCT_OPTIONS Multiple transfer structures specified.
FTP_ERR_MODE_OPTIONS Multiple transfer modes specified.
FTP_ERR_OVERFLOW ftp_dir() user specified buffer (locbuff)
too small.
FTP_ERR_REM_ACCESS Unable to access, create, delete, or rename
the specified remote pathname during an
ftpdel, ftpmkdir, ftprmdir, ftprename,
or ftpdir operation.
Licensed material--property of copyright holder(s) 5
ftp_xfer(3N) TCP/IP 5.4R3.00 ftp_xfer(3N)
SEE ALSO
ftp(1C), ftpd(1M).
Licensed material--property of copyright holder(s) 6