ftp_xfer(3N) SDK R4.11 ftp_xfer(3N)
NAME
ftp_xfer, ftp_dir, ftp_del, ftp_mkdir, ftp_rename, ftp_rmdir,
ftperror - implement the programmable interface to the File Transfer
Protocol
SYNOPSIS
#include <arpa/pftp.h>
void ftp_xfer (char *username, char *password, char *hostname, char
*loc_path, char *rem_path, int *code);
void ftp_dir (char *username, char *password, char *hostname, char
*rem_path, char *loc_buff, int *buf_size, int *code);
void ftp_del (char *username, char *password, char *hostname, char
*rem_path, int *code);
void ftp_mkdir (char *username, char *password, char *hostname, char
*rem_path, int *code);
void ftp_rename (char *username, char *password, char *hostname, char
*frompath, char *to_path, int *code);
void ftp_rmdir (char *username, char *password, char *hostname, char
*rem_path, 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.
loc_path 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.
rem_path 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.
loc_buff A user-supplied buffer to receive the text information
returned by the FTP dir command.
buf_size A pointer to an integer containing the size of loc_buff
initially, and the number of characters returned in
loc_buff on completion.
frompath A string containing the filename (pathname) of the file to
be renamed on the remote host.
to_path 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.
DESCRIPTION
This set of library routines implement the programmable interface to
the File Transfer Protocol (FTP) application.
ftp_xfer 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 loc_path and rem_path. The
transfer direction, mode, structure, and type must be specified in
code. Command completion status is returned in code.
ftp_dir returns in loc_buff the output from the FTP dir command. FTP
logs in to hostname using username and password. rem_path specifies
the remote directory to list on hostname. loc_buff is written with
the output of the FTP dir command and is not null-terminated. If the
output is smaller than buf_size, loc_buff is padded with spaces. If
the output is larger than buf_size, the call will fail with an
FTP_ERR_OVERFLOW error. Upon completion, buf_size contains the
number of output characters (excluding the space padding) returned in
loc_buff. Command completion status is returned in code.
ftp_del deletes the file specified in rem_path on the remote host
hostname. FTP logs in to hostname using username and password.
rem_path specifies the remote file to delete. Command completion
status is returned in code.
ftp_mkdir creates the directory specified in rem_path on the remote
host hostname. FTP logs in to hostname using username and password.
rem_path specifies the remote directory to create. ftp_mkdir will
fail if rem_path already exists. Command completion status is
returned in code.
ftp_rename renames the file specified in frompath on the remote host
hostname to the file specified in to_path. FTP logs in to hostname
using username and password. If to_path exists, it will be
overwritten. Command completion status is returned in code.
ftp_rmdir deletes the directory specified in rem_path 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<process_ID>. (Note that this
is not the same as the FTP debug command.) The output
produced by selecting FTP_DEBUG is similar to the text
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 ftp_xfer().
One of the following file transfer directions is required by
ftp_xfer():
FTP_GET_OP Retrieve the rem_path file from hostname into loc_path on
the local host.
FTP_PUT_OP Store the loc_path file on the local host into rem_path
on hostname.
One of the following file transfer modes is required by ftp_xfer():
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
ftp_xfer():
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 ftp_xfer():
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.
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
ftp_xfer():
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 F77_FTP
C
#include "arpa/pftp.h"
C
CHARACTER*FTP_USERNAME_LEN USERNAME
CHARACTER*FTP_PASSWORD_LEN PASSWORD
CHARACTER*FTP_HOSTNAME_LEN HOSTNAME
CHARACTER*FTP_LOC_PATH_LEN LOC_PATHNAME
CHARACTER*FTP_REM_PATH_LEN REM_PATHNAME
INTEGER CODE
CHARACTER*2048 BUFF
CHARACTER*FTP_MAXERRSTR_LEN ERRSTR
INTEGER BUF_SIZE
CHARACTER*FTP_LOC_PATH_LEN OLD_PATHNAME
CHARACTER*FTP_REM_PATH_LEN NEW_PATHNAME
C
CALL FTP_XFER(USERNAME,PASSWORD,HOSTNAME,
& LOC_PATHNAME,REM_PATHNAME,CODE)
C
CALL FTP_RENAME(USERNAME,PASSWORD,HOSTNAME,
& OLD_PATHNAME,NEW_PATHNAME,CODE)
C
CALL FTP_MKDIR(USERNAME,PASSWORD,HOSTNAME,REM_PATHNAME,CODE)
C
CALL FTP_DIR(USERNAME,PASSWORD,HOSTNAME,REM_PATHNAME,
& BUFF,BUF_SIZE,CODE)
C
CALL FTP_DEL(USERNAME,PASSWORD,HOSTNAME,REM_PATHNAME,CODE)
C
CALL FTP_RMDIR(USERNAME,PASSWORD,HOSTNAME,REM_PATHNAME,CODE)
C
CALL FTPERROR(CODE,ERRSTR,BUF_SIZE)
C
END
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 (loc_buff)
too small.
FTP_ERR_REM_ACCESS Unable to access, create, delete, or rename
the specified remote pathname during an
ftp_del, ftp_mkdir, ftp_rmdir, ftp_rename,
or ftp_dir operation.
SEE ALSO
ftp(1C), ftpd(1M).
Licensed material--property of copyright holder(s)