GLOBUS_FTP_CONTROL_HANDLE_DESTROY(3)

💖 NAME 💖

globus_ftp_control_client — GridFTP Control Client 👑

• Control Client.

---

✨ SYNOPSIS ✨

🌸 Functions 🌸

• globus_ftp_control_handle_init — Initialize a globus ftp handle.

globus_result_t globus_ftp_control_handle_init (globus_ftp_control_handle_t *handle)

• globus_ftp_control_handle_destroy — Destroy a globus ftp handle.

globus_result_t globus_ftp_control_handle_destroy (globus_ftp_control_handle_t *handle)

• globus_ftp_control_connect — Create a new control connection to an FTP server.

globus_result_t globus_ftp_control_connect (globus_ftp_control_handle_t *handle, char *host, unsigned short port, globus_ftp_control_response_callback_t callback, void *callback_arg)

• globus_ftp_control_response_destroy — Free the memory associated with a response.

globus_result_t globus_ftp_control_response_destroy (globus_ftp_control_response_t *response)

• globus_ftp_control_response_copy — Copy a response structure.

globus_result_t globus_ftp_control_response_copy (globus_ftp_control_response_t *src, globus_ftp_control_response_t *dest)

• globus_ftp_control_authenticate — Authenticate the user to the FTP server.

globus_result_t globus_ftp_control_authenticate (globus_ftp_control_handle_t *handle, globus_ftp_control_auth_info_t *auth_info, globus_bool_t use_auth, globus_ftp_control_response_callback_t callback, void *callback_arg)

• globus_ftp_control_authenticate_ex — Authenticate the user to the FTP server.

globus_result_t globus_ftp_control_authenticate_ex (globus_ftp_control_handle_t *handle, globus_ftp_control_auth_info_t *auth_info, globus_bool_t use_auth, globus_ftp_control_response_callback_t callback, void *callback_arg)

• globus_ftp_control_send_command — Send an FTP protocol command.

globus_result_t globus_ftp_control_send_command (globus_ftp_control_handle_t *handle, const char *cmdspec, globus_ftp_control_response_callback_t callback, void *callback_arg,...)

• globus_ftp_control_abort — Send a GridFTP ABORT.

globus_result_t globus_ftp_control_abort (globus_ftp_control_handle_t *handle, globus_ftp_control_response_callback_t callback, void *callback_arg)

• globus_ftp_control_quit — Send a GridFTP QUIT.

globus_result_t globus_ftp_control_quit (globus_ftp_control_handle_t *handle, globus_ftp_control_response_callback_t callback, void *callback_arg)

• globus_ftp_control_force_close — Force a control connection to close.

globus_result_t globus_ftp_control_force_close (globus_ftp_control_handle_t *handle, globus_ftp_control_response_callback_t callback, void *callback_arg)

• globus_ftp_control_auth_info_init — Initialize authentication information.

globus_result_t globus_ftp_control_auth_info_init (globus_ftp_control_auth_info_t *auth_info, gss_cred_id_t credential_handle, globus_bool_t encrypt, char *user, char *password, char *account, char *subject)

• globus_ftp_control_auth_info_compare — Compare authentication information.

int globus_ftp_control_auth_info_compare (globus_ftp_control_auth_info_t *auth_info_1, globus_ftp_control_auth_info_t *auth_info_2)

• globus_ftp_control_client_get_connection_info_ex — Not documented yet.

globus_result_t globus_ftp_control_client_get_connection_info_ex (globus_ftp_control_handle_t *handle, globus_ftp_control_host_port_t *local_info, globus_ftp_control_host_port_t *remote_info)

• globus_ftp_control_ipv6_allow — Not documented yet.

globus_result_t globus_ftp_control_ipv6_allow (globus_ftp_control_handle_t *handle, globus_bool_t allow)

---

🦋 Detailed Description 🦋

Control Client.

---

👑 Function Documentation 👑

💜 globus_result_t globus_ftp_control_abort

globus_result_t globus_ftp_control_abort (globus_ftp_control_handle_t *handle, globus_ftp_control_response_callback_t callback, void *callback_arg)

okay bestie, this one is literally the Send a GridFTP ABORT girlie. You use it to fire the ABORT message at the FTP server. The tea is that ABORT goes out out-of-band, and it terminates whatever data transfer is currently in progress. 🛑

As a direct result of the ABORT, the data channels used by this control channel get closed. The data command callback gets issued with either a completion reply or a transfer aborted reply. And the ABORT callback also gets invoked, carrying the server's response to the abort command. 💅

⚠️ Any attempts to register buffers for read or write after an ABORT has been sent will fail with a "no transfer in progress" error. So don't do that. 🙈

Parameters

• handle — A pointer to a GridFTP control handle. The ABORT command is issued to the server over the control channel associated with this handle.
• callback — The function to be called once the authentication process is complete or when an error occurs.
• callback_arg — User supplied argument to the callback function

Returns

• Success
• Null handle
• No transfer in progress

Callback errors:

• success
• protocol error
• eof

Expected callback response values:

• 226 Abort successful.
• 500 Syntax error, command unrecognized.

Note — The server may send other responses. 👀

---

💜 int globus_ftp_control_auth_info_compare

int globus_ftp_control_auth_info_compare (globus_ftp_control_auth_info_t *auth_info_1, globus_ftp_control_auth_info_t *auth_info_2)

Compare authentication information. This helper function compares two authentication information structures and returns zero if the two structures are deemed equal, and a non-zero value otherwise. ✨

Parameters

• auth_info_1 — The first authentication structure
• auth_info_2 — The second authentication structure

Returns

• 0 if the structures are equal
• !0 if the structures differ or an error occurred

---

💜 globus_result_t globus_ftp_control_auth_info_init

globus_result_t globus_ftp_control_auth_info_init (globus_ftp_control_auth_info_t *auth_info, gss_cred_id_t credential_handle, globus_bool_t encrypt, char *user, char *password, char *account, char *subject)

Initialize authentication information. This helper function initializes an authentication information structure with the values contained in the second to fifth arguments, which may be GLOBUS_NULL. Bestie, listen: no memory is allocated in this function. 🎀

Parameters

• auth_info — The authentication structure to initialize.
• credential_handle — The credential to use for authentication. This may be GSS_C_NO_CREDENTIAL to use the user's default credential.
• encrypt — Boolean whether or not to encrypt the control channel for this handle.
• user — The user name
• password — The password for the user name
• account — The account for the user name/password
• subject — The GSSAPI subject name

Returns

• Error object
• GLOBUS_SUCCESS

---

💜 globus_result_t globus_ftp_control_authenticate

globus_result_t globus_ftp_control_authenticate (globus_ftp_control_handle_t *handle, globus_ftp_control_auth_info_t *auth_info, globus_bool_t use_auth, globus_ftp_control_response_callback_t callback, void *callback_arg)

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. 🤝

Note — Do we want to add attribute arguments for: - specifying type of delegation - gsswrap control messages for integrity or confidentiality

Parameters

• handle — A pointer to a unauthenticated GridFTP control handle. In the case of GSS authentication the GSS security context is stored in this structure.
• auth_info — This structure is used to pass the following information:
  • 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.
  • 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.
  • account — This parameter is optional. If not used it should be set to GLOBUS_NULL. It might be needed by firewalls.
  • 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.
• use_auth — If set to GLOBUS_TRUE the above argument indicates that GSS authentication should be used, otherwise cleartext user/password authentication is used.
• callback — The function to be called once the authentication process is complete or when an error occurs.
• callback_arg — User supplied argument to the callback function

Returns

• success
• Null handle
• Invalid handle
• Handle already authenticated

Callback errors:

• success
• authentication failed
• protocol error
• eof

Expected callback response values:

• 230 User logged in, proceed.
• 232 User logged in, authorized by security data exchange.
• 234 Security data exchange complete.
• 331 User name okay, need password.
• 332 Need account for login.
• 336 Username okay, need password. Challenge is "...."
• 431 Need some unavailable resource to process security.
• 500 Syntax error, command unrecognized.
• 530 Not logged in.

Note — The server may send other responses. The function globus_ftp_control_authenticate_ex() 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. 🔥

---

💜 globus_result_t globus_ftp_control_authenticate_ex

globus_result_t globus_ftp_control_authenticate_ex (globus_ftp_control_handle_t *handle, globus_ftp_control_auth_info_t *auth_info, globus_bool_t use_auth, globus_ftp_control_response_callback_t callback, void *callback_arg)

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. 🌈

Note — Do we want to add attribute arguments for: - specifying type of delegation - gsswrap control messages for integrity or confidentiality

Parameters

• handle — A pointer to a unauthenticated GridFTP control handle. In the case of GSS authentication the GSS security context is stored in this structure.
• auth_info — This structure is used to pass the following information:
  • 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.
• password — bestie, this is the password for the user we just talked about. But heads up: if user is "anonymous" or "ftp", or if gss_auth is true, then this lil string is allowed to be GLOBUS_NULL. Slay, no password needed.
• account — totally optional, boo. If you don't need it, set it to GLOBUS_NULL. Firewalls sometimes want it though, so like, don't be surprised.
• auth_gssapi_subject — the GSSAPI subject name of the server you're connecting to. If this is GLOBUS_NULL and gss_auth is set to GLOBUS_TRUE, the name just defaults to the host name. Convenient ✨.
• use_auth — if you set this to GLOBUS_TRUE, the argument above means "hey use GSS authentication". Otherwise it's plain cleartext user/password auth. Choose wisely 💅.
• callback — the function that gets called once auth is done, or whenever an error happens. Your moment.
• callback_arg — your own lil user-supplied argument that gets handed to the callback. 🎀

Returns 💖

• success
• Null handle
• Invalid handle
• Handle already authenticated

Callback errors:

• success
• authentication failed
• protocol error
• eof

Expected callback response values:

• 230 User logged in, proceed.
• 232 User logged in, authorized by security data exchange.
• 234 Security data exchange complete.
• 331 User name okay, need password.
• 332 Need account for login.
• 336 Username okay, need password. Challenge is "...."
• 431 Need some unavailable resource to process security.
• 500 Syntax error, command unrecognized.
• 530 Not logged in.

Note 🫶

The server may send other responses. iykyk.

The function globus_ftp_control_authenticate_ex() is literally 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 what you want, you must set them explicitly. And it is the caller's responsibility to make sure req_flags only contains valid flags. No pressure bestie, just like, correctness.

---

globus_ftp_control_connect 😌

globus_result_t globus_ftp_control_connect (globus_ftp_control_handle_t *
    handle, char * host, unsigned short port,
    globus_ftp_control_response_callback_t callback, void * callback_arg)

Create a new control connection to an FTP server. This is the function you call to kick off an FTP control connection — it makes the socket to the FTP server. Once the connection is made and the server's identification string arrives, your callback gets invoked. Main character energy.

Parameters

• handle — a pointer to an initialized FTP control handle. This handle gets used for all subsequent FTP control operations, so like, treasure it.
• host — the hostname of the FTP server.
• port — the TCP port number of the FTP server.
• callback — a function called once the connection to the server is established and a response has been read.
• callback_arg — parameter to the callback function.

Returns

• success
• Null handle
• Null host
• Illegal port number
• Null callback
• Cannot resolve hostname
• Cannot create socket

Callback errors:

• success
• connection refused
• protocol error
• eof

Expected callback response values:

• 120 Service ready in nnn minutes.
• 220 Service ready for new user.
• 421 Service not available, closing control connection.
• 500 Syntax error, command unrecognized.

Note

The server may send other responses. 💀 Always.

---

globus_ftp_control_force_close 🙈

globus_result_t globus_ftp_control_force_close (globus_ftp_control_handle_t
    * handle, globus_ftp_control_response_callback_t callback, void *
    callback_arg)

Force a control connection to close. It force-closes the control connection without waiting for outstanding commands to complete and without sending QUIT. Yeah. Just like that.

This function closes 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. Gone. Done. Periodt.

Note

Since this function waits until all other callbacks are completed before calling its own callback, it may not be called in a blocking fashion from another callback. That's a trap bestie, don't fall in.

Parameters

• handle — a pointer to a GridFTP control handle. The quit message is issued to the server over the control channel associated with this handle.
• callback — the function to be called once the authentication process is complete or when an error occurs.
• callback_arg — user supplied argument to the callback function

Returns

• Success
• Null handle

Callback errors:

• success
• failure

Expected callback response values:

• GLOBUS_NULL

---

globus_ftp_control_handle_destroy 🌸

globus_result_t globus_ftp_control_handle_destroy
    (globus_ftp_control_handle_t * handle)

Destroy a globus ftp handle. This frees up all dynamically allocated memory associated with a given globus ftp handle. It also removes the handle from a list used by the module activation/deactivation functions. Important: this should only be called after a call to either globus_ftp_control_force_close or globus_ftp_control_quit. Otherwise, no.

Parameters

• handle — the handle to destroy.

Returns

• success
• invalid handle
• handle is still in connected state

---

globus_ftp_control_handle_init ✨

globus_result_t globus_ftp_control_handle_init (globus_ftp_control_handle_t
    * handle)

Initialize a globus ftp handle. This sets up a globus ftp handle (i.e. initializes all the mutexes and variables). It also enters the handle in a list used by the module activation/deactivation functions. Start here, bestie, it's giving setup.

Parameters

• handle — the handle to initialize.

Returns

• GLOBUS_SUCCESS
• error object

---

globus_ftp_control_quit 🦋

globus_result_t globus_ftp_control_quit (globus_ftp_control_handle_t *
    handle, globus_ftp_control_response_callback_t callback, void *
    callback_arg)

Send a GridFTP QUIT. This closes the control channel to the FTP server, the polite way. 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.

Note

Need to further define behavior for when a QUIT happens during a transfer or command is in progress. (yes, that's literally what the docs say, we're all just living with it)

Since this function waits until all other callbacks are completed before calling its own callback, it may not be called in a blocking fashion from another callback. Same energy as before, same warning.

Parameters

• handle — a pointer to a GridFTP control handle. The quit message is issued to the server over the control channel associated with this handle.
• callback — the function to be called once the authentication process is complete or when an error occurs.
• callback_arg — user supplied argument to the callback function

Returns

• Success
• Null handle
• Command in progress

Callback errors:

• success
• protocol error
• eof

Expected callback response values:

• 221 Service closing control connection.
• 500 Syntax error, command unrecognized.

Note

The server may send other responses. 🫠 Obviously.

---

globus_ftp_control_response_copy 🎀

globus_result_t globus_ftp_control_response_copy
    (globus_ftp_control_response_t * src, globus_ftp_control_response_t *
    dest)

Copy a response structure. This is a lil helper function which copies one response structure to another. That's it. That's the whole vibe. 🌈

Parameters

• src — this parameter indicates the response structure to copy
• dest — this parameter specifies the target response structure

Returns

• Error object
• GLOBUS_SUCCESS

---

globus_ftp_control_response_destroy 💜

globus_result_t globus_ftp_control_response_destroy
    (globus_ftp_control_response_t * response)

Free the memory associated with a response. Another helper function — it frees the memory associated with a response structure. Clean up after yourself, bestie. 🧚

Parameters

• response — this parameter indicates the response structure to destroy

Returns

• Error object
• GLOBUS_SUCCESS

---

globus_ftp_control_send_command 🔥

globus_result_t globus_ftp_control_send_command (globus_ftp_control_handle_t
    * handle, const char * cmdspec, globus_ftp_control_response_callback_t
    callback, void * callback_arg,  ...)

Send an FTP protocol command. This sends an FTP command and registers a handler to receive the FTP reply (or replies, if an intermediate one gets sent). And when the control channel is gss authenticated, the message and the reply are automatically gss wrapped/unwrapped. Iconic behaviour, honestly. 👑

Parameters

• handle — 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.
• cmdspec — 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.
• callback — the function to be called once the authentication process is complete or when an error occurs.
• callback_arg — user supplied argument to the callback function
• ... — parameters which will be substituted into the % escapes in the cmdspec string.

Returns

• Success
• Null handle
• Command already in progress

Callback errors:

• success
• protocol error
• eof

Expected callback response values:

Any defined in RFC 959, 2228, 2389, draft-ietf-ftpext-mlst-10, or the protocol extensions document. So like, the whole extended universe of responses. 🌌

---

Author ⭐

Generated automatically by Doxygen for globus_ftp_control from the source code. (So if anything's weird, blame the robots, not me. 💀)

---

Okay that's the whole page bestie!! This was globus_ftp_control, Version 9.10, living in the globus_ftp...trol_client(3) manual page — go forth and control your FTP with confidence, no cap. 💖✨🎀🦋🌸💅🫶