.TH "globus_ftp_control_client" 3 "Mon Dec 14 2020" "Version 9.6" "globus_ftp_control" \" -*- nroff -*- .ad l .nh .SH NAME globus_ftp_control_client \- GridFTP Control Client .PP \- Control Client\&. .SH SYNOPSIS .br .PP .SS "Functions" .in +1c .ti -1c .RI "globus_result_t \fBglobus_ftp_control_handle_init\fP (globus_ftp_control_handle_t *handle)" .br .RI "Initialize a globus ftp handle\&. " .ti -1c .RI "globus_result_t \fBglobus_ftp_control_handle_destroy\fP (globus_ftp_control_handle_t *handle)" .br .RI "Destroy a globus ftp handle\&. " .ti -1c .RI "globus_result_t \fBglobus_ftp_control_connect\fP (globus_ftp_control_handle_t *handle, char *host, unsigned short port, \fBglobus_ftp_control_response_callback_t\fP callback, void *callback_arg)" .br .RI "Create a new control connection to an FTP server\&. " .ti -1c .RI "globus_result_t \fBglobus_ftp_control_response_destroy\fP (globus_ftp_control_response_t *response)" .br .RI "Free the memory associated with a response\&. " .ti -1c .RI "globus_result_t \fBglobus_ftp_control_response_copy\fP (globus_ftp_control_response_t *src, globus_ftp_control_response_t *dest)" .br .RI "Copy a response structure\&. " .ti -1c .RI "globus_result_t \fBglobus_ftp_control_authenticate\fP (globus_ftp_control_handle_t *handle, \fBglobus_ftp_control_auth_info_t\fP *auth_info, globus_bool_t use_auth, \fBglobus_ftp_control_response_callback_t\fP callback, void *callback_arg)" .br .RI "Authenticate the user to the FTP server\&. " .ti -1c .RI "globus_result_t \fBglobus_ftp_control_authenticate_ex\fP (globus_ftp_control_handle_t *handle, \fBglobus_ftp_control_auth_info_t\fP *auth_info, globus_bool_t use_auth, \fBglobus_ftp_control_response_callback_t\fP callback, void *callback_arg)" .br .RI "Authenticate the user to the FTP server\&. " .ti -1c .RI "globus_result_t \fBglobus_ftp_control_send_command\fP (globus_ftp_control_handle_t *handle, const char *cmdspec, \fBglobus_ftp_control_response_callback_t\fP callback, void *callback_arg,\&.\&.\&.)" .br .RI "Send an FTP protocol command\&. " .ti -1c .RI "globus_result_t \fBglobus_ftp_control_abort\fP (globus_ftp_control_handle_t *handle, \fBglobus_ftp_control_response_callback_t\fP callback, void *callback_arg)" .br .RI "Send a GridFTP ABORT\&. " .ti -1c .RI "globus_result_t \fBglobus_ftp_control_quit\fP (globus_ftp_control_handle_t *handle, \fBglobus_ftp_control_response_callback_t\fP callback, void *callback_arg)" .br .RI "Send a GridFTP QUIT\&. " .ti -1c .RI "globus_result_t \fBglobus_ftp_control_force_close\fP (globus_ftp_control_handle_t *handle, \fBglobus_ftp_control_response_callback_t\fP callback, void *callback_arg)" .br .RI "Force a control connection to close\&. " .ti -1c .RI "globus_result_t \fBglobus_ftp_control_auth_info_init\fP (\fBglobus_ftp_control_auth_info_t\fP *auth_info, gss_cred_id_t credential_handle, globus_bool_t encrypt, char *user, char *password, char *account, char *subject)" .br .RI "Initialize authentication information\&. " .ti -1c .RI "int \fBglobus_ftp_control_auth_info_compare\fP (\fBglobus_ftp_control_auth_info_t\fP *auth_info_1, \fBglobus_ftp_control_auth_info_t\fP *auth_info_2)" .br .RI "Compare authentication information\&. " .ti -1c .RI "globus_result_t \fBglobus_ftp_control_client_get_connection_info_ex\fP (globus_ftp_control_handle_t *handle, globus_ftp_control_host_port_t *local_info, globus_ftp_control_host_port_t *remote_info)" .br .RI "Not documented yet\&. " .ti -1c .RI "globus_result_t \fBglobus_ftp_control_ipv6_allow\fP (globus_ftp_control_handle_t *handle, globus_bool_t allow)" .br .RI "Not documented yet\&. " .in -1c .SH "Detailed Description" .PP Control Client\&. .SH "Function Documentation" .PP .SS "globus_result_t globus_ftp_control_abort (globus_ftp_control_handle_t * handle, \fBglobus_ftp_control_response_callback_t\fP callback, void * callback_arg)" .PP Send a GridFTP ABORT\&. This function is used to send the ABORT message to the FTP server\&. The ABORT message is sent out-of-band, and terminates any current data transfer in progress\&. .PP As a result of the ABORT, the data channels used by this control channel will be closed\&. The data command callback will be issued with either a completion reply, or a transfer aborted reply\&. The ABORT callback will also be invoked, with the server's response to the abort command\&. .PP Any attempts to register buffers for read or write after an ABORT has been sent will fail with a 'no transfer in progress' error\&. .PP \fBParameters\fP .RS 4 \fIhandle\fP A pointer to a GridFTP control handle\&. The ABORT command is issued to the server over the control channel associated with this handle\&. .br \fIcallback\fP The function to be called once the authentication process is complete or when an error occurs\&. .br \fIcallback_arg\fP User supplied argument to the callback function .RE .PP \fBReturns\fP .RS 4 .IP "\(bu" 2 Success .IP "\(bu" 2 Null handle .IP "\(bu" 2 No transfer in progress .PP .RE .PP \fBCallback errors:\fP .RS 4 .IP "\(bu" 2 success .IP "\(bu" 2 protocol error .IP "\(bu" 2 eof .PP .RE .PP \fBExpected callback response values:\fP .RS 4 .IP "\(bu" 2 226 Abort successful\&. .IP "\(bu" 2 500 Syntax error, command unrecognized\&. .PP .RE .PP \fBNote\fP .RS 4 The server may send other responses\&. .RE .PP .SS "int globus_ftp_control_auth_info_compare (\fBglobus_ftp_control_auth_info_t\fP * auth_info_1, \fBglobus_ftp_control_auth_info_t\fP * auth_info_2)" .PP Compare authentication information\&. This is helper function compares two authentication information structures and return zero if the two structures are deemed equal and a non-zero value otherwise\&. .PP \fBParameters\fP .RS 4 \fIauth_info_1\fP The first authentication structure .br \fIauth_info_2\fP The second authentication structure .RE .PP \fBReturns\fP .RS 4 .IP "\(bu" 2 0 if the structures are equal .IP "\(bu" 2 !0 if the structures differ or an error occurred .PP .RE .PP .SS "globus_result_t globus_ftp_control_auth_info_init (\fBglobus_ftp_control_auth_info_t\fP * auth_info, gss_cred_id_t credential_handle, globus_bool_t encrypt, char * user, char * password, char * account, char * subject)" .PP Initialize authentication information\&. This is helper function initializes a authentication information structure with the values contained in the second to fifth arguments, which may be GLOBUS_NULL\&. No memory is allocated in this function\&. .PP \fBParameters\fP .RS 4 \fIauth_info\fP The authentication structure to initialize\&. .br \fIcredential_handle\fP The credential to use for authentication\&. This may be GSS_C_NO_CREDENTIAL to use the user's default credential\&. .br \fIencrypt\fP Boolean whether or not to encrypt the control channel for this handle\&. .br \fIuser\fP The user name .br \fIpassword\fP The password for the user name .br \fIaccount\fP The account for the user name/password .br \fIsubject\fP The GSSAPI subject name .RE .PP \fBReturns\fP .RS 4 .IP "\(bu" 2 Error object .IP "\(bu" 2 GLOBUS_SUCCESS .PP .RE .PP .SS "globus_result_t globus_ftp_control_authenticate (globus_ftp_control_handle_t * handle, \fBglobus_ftp_control_auth_info_t\fP * auth_info, globus_bool_t use_auth, \fBglobus_ftp_control_response_callback_t\fP callback, void * callback_arg)" .PP Authenticate the user to the FTP server\&. This will perform the authentication handshake with the FTP server\&. Depending on which parameters are non-NULL, the authentication may involve GSSAPI credentials, a username, a password, and an account name\&. .PP \fBNote\fP .RS 4 Do we want to add attribute arguments for: .IP "\(bu" 2 specifying type of delegation .IP "\(bu" 2 gsswrap control messages for integrity or confidentiality .PP .RE .PP \fBParameters\fP .RS 4 \fIhandle\fP A pointer to a unauthenticated GridFTP control handle\&. In the case of GSS authentication the GSS security context is stored in this structure\&. .br \fIauth_info\fP This structure is used to pass the following information: .IP "\(bu" 2 user The user's name for login purposes\&. If this string is 'anonymous', 'ftp', GLOBUS_NULL or ':globus-mapping:' then the password argument is optional\&. If this string is GLOBUS_NULL or ':globus-mapping:' and gss_auth is true then the users login is looked by the FTP server host\&. .IP "\(bu" 2 password The password for the above user argument\&. If the user argument is 'anonymous' or 'ftp' or if gss_auth is true this string may be GLOBUS_NULL\&. .br .IP "\(bu" 2 account This parameter is optional\&. If not used it should be set to GLOBUS_NULL\&. It might be needed by firewalls\&. .IP "\(bu" 2 auth_gssapi_subject The GSSAPI subject name of the server you are connecting to\&. If this is GLOBUS_NULL, and the gss_auth parameter is set to GLOBUS_TRUE, then the name will default to the host name\&. .PP .br \fIuse_auth\fP If set to GLOBUS_TRUE the above argument indicates that GSS authentication should be used, otherwise cleartext user/password authentication is used\&. .br \fIcallback\fP The function to be called once the authentication process is complete or when an error occurs\&. .br \fIcallback_arg\fP User supplied argument to the callback function .RE .PP \fBReturns\fP .RS 4 .IP "\(bu" 2 success .IP "\(bu" 2 Null handle .IP "\(bu" 2 Invalid handle .IP "\(bu" 2 Handle already authenticated .PP .RE .PP \fBCallback errors:\fP .RS 4 .IP "\(bu" 2 success .IP "\(bu" 2 authentication failed .IP "\(bu" 2 protocol error .IP "\(bu" 2 eof .PP .RE .PP \fBExpected callback response values:\fP .RS 4 .IP "\(bu" 2 230 User logged in, proceed\&. .IP "\(bu" 2 232 User logged in, authorized by security data exchange\&. .IP "\(bu" 2 234 Security data exchange complete\&. .IP "\(bu" 2 331 User name okay, need password\&. .IP "\(bu" 2 332 Need account for login\&. .IP "\(bu" 2 336 Username okay, need password\&. Challenge is '\&.\&.\&.\&.' .IP "\(bu" 2 431 Need some unavailable resource to process security\&. .IP "\(bu" 2 500 Syntax error, command unrecognized\&. .IP "\(bu" 2 530 Not logged in\&. .PP .RE .PP \fBNote\fP .RS 4 The server may send other responses\&. .PP The function \fBglobus_ftp_control_authenticate_ex()\fP is identical except that the auth_info->req_flags is used\&. If delegation flags or any flags other than GSS_C_MUTUAL_FLAG and GSS_C_CONF_FLAG are desired, they must be set explicitly\&. It is the caller's responsibility to ensure that req_flags only contains valid flags\&. .RE .PP .SS "globus_result_t globus_ftp_control_authenticate_ex (globus_ftp_control_handle_t * handle, \fBglobus_ftp_control_auth_info_t\fP * auth_info, globus_bool_t use_auth, \fBglobus_ftp_control_response_callback_t\fP callback, void * callback_arg)" .PP Authenticate the user to the FTP server\&. This will perform the authentication handshake with the FTP server\&. Depending on which parameters are non-NULL, the authentication may involve GSSAPI credentials, a username, a password, and an account name\&. .PP \fBNote\fP .RS 4 Do we want to add attribute arguments for: .IP "\(bu" 2 specifying type of delegation .IP "\(bu" 2 gsswrap control messages for integrity or confidentiality .PP .RE .PP \fBParameters\fP .RS 4 \fIhandle\fP A pointer to a unauthenticated GridFTP control handle\&. In the case of GSS authentication the GSS security context is stored in this structure\&. .br \fIauth_info\fP This structure is used to pass the following information: .IP "\(bu" 2 user The user's name for login purposes\&. If this string is 'anonymous', 'ftp', GLOBUS_NULL or ':globus-mapping:' then the password argument is optional\&. If this string is GLOBUS_NULL or ':globus-mapping:' and gss_auth is true then the users login is looked by the FTP server host\&. .IP "\(bu" 2 password The password for the above user argument\&. If the user argument is 'anonymous' or 'ftp' or if gss_auth is true this string may be GLOBUS_NULL\&. .br .IP "\(bu" 2 account This parameter is optional\&. If not used it should be set to GLOBUS_NULL\&. It might be needed by firewalls\&. .IP "\(bu" 2 auth_gssapi_subject The GSSAPI subject name of the server you are connecting to\&. If this is GLOBUS_NULL, and the gss_auth parameter is set to GLOBUS_TRUE, then the name will default to the host name\&. .PP .br \fIuse_auth\fP If set to GLOBUS_TRUE the above argument indicates that GSS authentication should be used, otherwise cleartext user/password authentication is used\&. .br \fIcallback\fP The function to be called once the authentication process is complete or when an error occurs\&. .br \fIcallback_arg\fP User supplied argument to the callback function .RE .PP \fBReturns\fP .RS 4 .IP "\(bu" 2 success .IP "\(bu" 2 Null handle .IP "\(bu" 2 Invalid handle .IP "\(bu" 2 Handle already authenticated .PP .RE .PP \fBCallback errors:\fP .RS 4 .IP "\(bu" 2 success .IP "\(bu" 2 authentication failed .IP "\(bu" 2 protocol error .IP "\(bu" 2 eof .PP .RE .PP \fBExpected callback response values:\fP .RS 4 .IP "\(bu" 2 230 User logged in, proceed\&. .IP "\(bu" 2 232 User logged in, authorized by security data exchange\&. .IP "\(bu" 2 234 Security data exchange complete\&. .IP "\(bu" 2 331 User name okay, need password\&. .IP "\(bu" 2 332 Need account for login\&. .IP "\(bu" 2 336 Username okay, need password\&. Challenge is '\&.\&.\&.\&.' .IP "\(bu" 2 431 Need some unavailable resource to process security\&. .IP "\(bu" 2 500 Syntax error, command unrecognized\&. .IP "\(bu" 2 530 Not logged in\&. .PP .RE .PP \fBNote\fP .RS 4 The server may send other responses\&. .PP The function \fBglobus_ftp_control_authenticate_ex()\fP is identical except that the auth_info->req_flags is used\&. If delegation flags or any flags other than GSS_C_MUTUAL_FLAG and GSS_C_CONF_FLAG are desired, they must be set explicitly\&. It is the caller's responsibility to ensure that req_flags only contains valid flags\&. .RE .PP .SS "globus_result_t globus_ftp_control_connect (globus_ftp_control_handle_t * handle, char * host, unsigned short port, \fBglobus_ftp_control_response_callback_t\fP callback, void * callback_arg)" .PP Create a new control connection to an FTP server\&. This function is used to initiate an FTP control connection\&. It creates the socket to the FTP server\&. When the connection is made to the server, and the server's identification string is received, the callback function will be invoked\&. .PP \fBParameters\fP .RS 4 \fIhandle\fP A pointer to a initialized FTP control handle\&. This handle will be used for all subsequent FTP control operations\&. .br \fIhost\fP The hostname of the FTP server\&. .br \fIport\fP The TCP port number of the FTP server\&. .br \fIcallback\fP A function to be called once the connection to the server is established, and a response has been read\&. .br \fIcallback_arg\fP Parameter to the callback function\&. .RE .PP \fBReturns\fP .RS 4 .IP "\(bu" 2 success .IP "\(bu" 2 Null handle .IP "\(bu" 2 Null host .IP "\(bu" 2 Illegal port number .IP "\(bu" 2 Null callback .IP "\(bu" 2 Cannot resolve hostname .IP "\(bu" 2 Cannot create socket .PP .RE .PP \fBCallback errors:\fP .RS 4 .IP "\(bu" 2 success .IP "\(bu" 2 connection refused .IP "\(bu" 2 protocol error .IP "\(bu" 2 eof .PP .RE .PP \fBExpected callback response values:\fP .RS 4 .IP "\(bu" 2 120 Service ready in nnn minutes\&. .IP "\(bu" 2 220 Service ready for new user\&. .IP "\(bu" 2 421 Service not available, closing control connection\&. .IP "\(bu" 2 500 Syntax error, command unrecognized\&. .PP .RE .PP \fBNote\fP .RS 4 The server may send other responses\&. .RE .PP .SS "globus_result_t globus_ftp_control_force_close (globus_ftp_control_handle_t * handle, \fBglobus_ftp_control_response_callback_t\fP callback, void * callback_arg)" .PP Force a control connection to close\&. Force a close of the control connection without waiting for outstanding commands to complete and without sending QUIT\&. .PP This function is used to close the control channel to the FTP server\&. Once the final response callback passed to this function is invoked, the control handle can no longer be used for any GridFTP control operations\&. .PP \fBNote\fP .RS 4 Since this function waits until all other callbacks are completed before calling it's own callback it may not be called in a blocking fashion from another callback\&. .RE .PP \fBParameters\fP .RS 4 \fIhandle\fP A pointer to a GridFTP control handle\&. The quit message is issued to the server over the control channel associated with this handle\&. .br \fIcallback\fP The function to be called once the authentication process is complete or when an error occurs\&. .br \fIcallback_arg\fP User supplied argument to the callback function .RE .PP \fBReturns\fP .RS 4 .IP "\(bu" 2 Success .IP "\(bu" 2 Null handle .PP .RE .PP \fBCallback errors:\fP .RS 4 .IP "\(bu" 2 success .IP "\(bu" 2 failure .PP .RE .PP \fBExpected callback response values:\fP .RS 4 .IP "\(bu" 2 GLOBUS_NULL .PP .RE .PP .SS "globus_result_t globus_ftp_control_handle_destroy (globus_ftp_control_handle_t * handle)" .PP Destroy a globus ftp handle\&. This function will free up all dynamically allocated memory associated with a given globus ftp handle\&. It will also remove the handle from a list used by the module activation/deactivation functions\&. This function should only be called after a call to either globus_ftp_control_force_close or globus_ftp_control_quit\&. .br .PP \fBParameters\fP .RS 4 \fIhandle\fP The handle to destroy\&. .RE .PP \fBReturns\fP .RS 4 .IP "\(bu" 2 success .IP "\(bu" 2 invalid handle .IP "\(bu" 2 handle is still in connected state .PP .RE .PP .SS "globus_result_t globus_ftp_control_handle_init (globus_ftp_control_handle_t * handle)" .PP Initialize a globus ftp handle\&. This function will set up (i\&.e\&. initialize all mutexes and variables) a globus ftp handle\&. It will also enter the handle in a list used by the module activation/deactivation functions\&. .PP \fBParameters\fP .RS 4 \fIhandle\fP The handle to initialize\&. .RE .PP \fBReturns\fP .RS 4 .IP "\(bu" 2 GLOBUS_SUCCESS .IP "\(bu" 2 error object .PP .RE .PP .SS "globus_result_t globus_ftp_control_quit (globus_ftp_control_handle_t * handle, \fBglobus_ftp_control_response_callback_t\fP callback, void * callback_arg)" .PP Send a GridFTP QUIT\&. This function is used to close the control channel to the FTP server\&. There should be no transfer commands in progress when this is called\&. Once the final response callback passed to this function is invoked, the control handle can no longer be used for any GridFTP control operations\&. .PP \fBNote\fP .RS 4 Need to further define behavior for when a QUIT happens during a transfer or command is in progress\&. .PP Since this function waits until all other callbacks are completed before calling it's own callback it may not be called in a blocking fashion from another callback\&. .RE .PP \fBParameters\fP .RS 4 \fIhandle\fP A pointer to a GridFTP control handle\&. The quit message is issued to the server over the control channel associated with this handle\&. .br \fIcallback\fP The function to be called once the authentication process is complete or when an error occurs\&. .br \fIcallback_arg\fP User supplied argument to the callback function .RE .PP \fBReturns\fP .RS 4 .IP "\(bu" 2 Success .IP "\(bu" 2 Null handle .IP "\(bu" 2 Command in progress .PP .RE .PP \fBCallback errors:\fP .RS 4 .IP "\(bu" 2 success .IP "\(bu" 2 protocol error .IP "\(bu" 2 eof .PP .RE .PP \fBExpected callback response values:\fP .RS 4 .IP "\(bu" 2 221 Service closing control connection\&. .IP "\(bu" 2 500 Syntax error, command unrecognized\&. .PP .RE .PP \fBNote\fP .RS 4 The server may send other responses\&. .RE .PP .SS "globus_result_t globus_ftp_control_response_copy (globus_ftp_control_response_t * src, globus_ftp_control_response_t * dest)" .PP Copy a response structure\&. This is a helper function which copies one response structure to another\&. .PP \fBParameters\fP .RS 4 \fIsrc\fP This parameter indicates the response structure to copy .br \fIdest\fP This parameter specifies the target response structure .RE .PP \fBReturns\fP .RS 4 .IP "\(bu" 2 Error object .IP "\(bu" 2 GLOBUS_SUCCESS .PP .RE .PP .SS "globus_result_t globus_ftp_control_response_destroy (globus_ftp_control_response_t * response)" .PP Free the memory associated with a response\&. This is a helper function which frees the memory associated with a response structure\&. .PP \fBParameters\fP .RS 4 \fIresponse\fP This parameter indicates the response structure to destroy .RE .PP \fBReturns\fP .RS 4 .IP "\(bu" 2 Error object .IP "\(bu" 2 GLOBUS_SUCCESS .PP .RE .PP .SS "globus_result_t globus_ftp_control_send_command (globus_ftp_control_handle_t * handle, const char * cmdspec, \fBglobus_ftp_control_response_callback_t\fP callback, void * callback_arg, \&.\&.\&.)" .PP Send an FTP protocol command\&. This function is used to send an FTP command, and register a handler to receive the FTP reply (or replies, if an intermediate one is sent)\&. When the control channel is gss authenticated, the message and the reply will be automatically gss wrapped/unwrapped\&. .PP \fBParameters\fP .RS 4 \fIhandle\fP A pointer to a GridFTP control handle\&. The command described by the cmdspec is issued to the server over the control channel associated with this handle\&. .br \fIcmdspec\fP A printf-style format string containing the text of the command to send to the server\&. The optional parameters to the format string are passed after the callback_arg in the function invocation\&. .br \fIcallback\fP The function to be called once the authentication process is complete or when an error occurs\&. .br \fIcallback_arg\fP User supplied argument to the callback function .br \fI\&.\&.\&.\fP Parameters which will be substituted into the % escapes in the cmdspec string\&. .RE .PP \fBReturns\fP .RS 4 .IP "\(bu" 2 Success .IP "\(bu" 2 Null handle .IP "\(bu" 2 Command already in progress .PP .RE .PP \fBCallback errors:\fP .RS 4 .IP "\(bu" 2 success .IP "\(bu" 2 protocol error .IP "\(bu" 2 eof .PP .RE .PP \fBExpected callback response values:\fP .RS 4 Any defined in RFC 959, 2228, 2389, draft-ietf-ftpext-mlst-10, or the \fBprotocol extensions\fP document\&. .RE .PP .SH "Author" .PP Generated automatically by Doxygen for globus_ftp_control from the source code\&.