GLOBUS_XIO_API(3)

📦
version 6.6 · 6 versions
, in fedora 43, fedora 44, ubuntu resolute, ubuntu stonking

💖 GLOBUS_XIO_API — the Globus XIO API 💖

okay bestie, sit down, hydrate, because this is the whole entire GLOBUS_XIO_API situation — it's Library Functions Manual material, it's long, and it's split into parts. This is part 1. We are NOT signing off at the end, we're just getting started. periodt. ✨

Globus XIO API. That's the whole vibe. It's the Globus XIO API. Iconic. 🦋

✨ SYNOPSIS ✨

🎀 Typedefs

typedef void(* globus_xio_accept_callback_t) (globus_xio_server_t server,
    globus_xio_handle_t handle, globus_result_t result, void *user_arg)

typedef void(* globus_xio_server_callback_t) (globus_xio_server_t server,
    void *user_arg)

typedef globus_bool_t(* globus_xio_timeout_callback_t)
    (globus_xio_handle_t handle, globus_xio_operation_type_t type, void
    *user_arg)

typedef void(* globus_xio_callback_t) (globus_xio_handle_t handle,
    globus_result_t result, void *user_arg)

typedef void(* globus_xio_data_callback_t) (globus_xio_handle_t handle,
    globus_result_t result, globus_byte_t *buffer, globus_size_t len,
    globus_size_t nbytes, globus_xio_data_descriptor_t data_desc, void
    *user_arg)

typedef void(* globus_xio_iovec_callback_t) (globus_xio_handle_t handle,
    globus_result_t result, globus_xio_iovec_t *iovec, int count,
    globus_size_t nbytes, globus_xio_data_descriptor_t data_desc, void
    *user_arg)

typedef enum globus_i_xio_op_type_e globus_xio_operation_type_t

🌸 Enumerations

enum globus_i_xio_op_type_e

enum globus_xio_handle_cmd_t { GLOBUS_XIO_GET_LOCAL_CONTACT = 12345,
    GLOBUS_XIO_GET_LOCAL_NUMERIC_CONTACT, GLOBUS_XIO_GET_REMOTE_CONTACT,
    GLOBUS_XIO_GET_REMOTE_NUMERIC_CONTACT, GLOBUS_XIO_SEEK,
    GLOBUS_XIO_SET_STRING_OPTIONS, GLOBUS_XIO_GET_STRING_OPTIONS,
    GLOBUS_XIO_GET_DRIVER_NAME }

💅 Functions

globus_result_t globus_xio_attr_init (globus_xio_attr_t *attr)
globus_result_t globus_xio_attr_cntl (globus_xio_attr_t attr,
    globus_xio_driver_t driver, int cmd,...)
globus_result_t globus_xio_attr_copy (globus_xio_attr_t *dst,
    globus_xio_attr_t src)
globus_result_t globus_xio_attr_destroy (globus_xio_attr_t attr)
globus_result_t globus_xio_stack_init (globus_xio_stack_t *stack,
    globus_xio_attr_t stack_attr)
globus_result_t globus_xio_stack_push_driver (globus_xio_stack_t stack,
    globus_xio_driver_t driver)
globus_result_t globus_xio_stack_copy (globus_xio_stack_t *dst,
    globus_xio_stack_t src)
globus_result_t globus_xio_stack_destroy (globus_xio_stack_t stack)
globus_result_t globus_xio_server_create (globus_xio_server_t *server,
    globus_xio_attr_t server_attr, globus_xio_stack_t stack)
globus_result_t globus_xio_server_get_contact_string
    (globus_xio_server_t server, char **contact_string)
globus_result_t globus_xio_server_register_close (globus_xio_server_t
    server, globus_xio_server_callback_t cb, void *user_arg)
globus_result_t globus_xio_server_close (globus_xio_server_t server)
globus_result_t globus_xio_server_cntl (globus_xio_server_t server,
    globus_xio_driver_t driver, int cmd,...)
globus_result_t globus_xio_server_accept (globus_xio_handle_t
    *out_handle, globus_xio_server_t server)
globus_result_t globus_xio_server_register_accept (globus_xio_server_t
    server, globus_xio_accept_callback_t cb, void *user_arg)
globus_result_t globus_xio_handle_create (globus_xio_handle_t *handle,
    globus_xio_stack_t stack)
globus_result_t globus_xio_data_descriptor_init
    (globus_xio_data_descriptor_t *data_desc, globus_xio_handle_t
    handle)
globus_result_t globus_xio_data_descriptor_destroy
    (globus_xio_data_descriptor_t data_desc)
globus_result_t globus_xio_data_descriptor_cntl
    (globus_xio_data_descriptor_t data_desc, globus_xio_driver_t driver,
    int cmd,...)
globus_result_t globus_xio_handle_cntl (globus_xio_handle_t handle,
    globus_xio_driver_t driver, int cmd,...)
globus_result_t globus_xio_register_open (globus_xio_handle_t handle,
    const char *contact_string, globus_xio_attr_t attr,
    globus_xio_callback_t cb, void *user_arg)
globus_result_t globus_xio_open (globus_xio_handle_t handle, const char
    *contact_string, globus_xio_attr_t attr)
globus_result_t globus_xio_register_read (globus_xio_handle_t handle,
    globus_byte_t *buffer, globus_size_t buffer_length, globus_size_t
    waitforbytes, globus_xio_data_descriptor_t data_desc,
    globus_xio_data_callback_t cb, void *user_arg)
globus_result_t globus_xio_read (globus_xio_handle_t handle,
    globus_byte_t *buffer, globus_size_t buffer_length, globus_size_t
    waitforbytes, globus_size_t *nbytes, globus_xio_data_descriptor_t
    data_desc)
globus_result_t globus_xio_register_readv (globus_xio_handle_t handle,
    globus_xio_iovec_t *iovec, int iovec_count, globus_size_t
    waitforbytes, globus_xio_data_descriptor_t data_desc,
    globus_xio_iovec_callback_t cb, void *user_arg)
globus_result_t globus_xio_readv (globus_xio_handle_t handle,
    globus_xio_iovec_t *iovec, int iovec_count, globus_size_t
    waitforbytes, globus_size_t *nbytes, globus_xio_data_descriptor_t
    data_desc)
globus_result_t globus_xio_register_write (globus_xio_handle_t handle,
    globus_byte_t *buffer, globus_size_t buffer_length, globus_size_t
    waitforbytes, globus_xio_data_descriptor_t data_desc,
    globus_xio_data_callback_t cb, void *user_arg)
globus_result_t globus_xio_write (globus_xio_handle_t handle,
    globus_byte_t *buffer, globus_size_t buffer_length, globus_size_t
    waitforbytes, globus_size_t *nbytes, globus_xio_data_descriptor_t
    data_desc)
globus_result_t globus_xio_register_writev (globus_xio_handle_t handle,
    globus_xio_iovec_t *iovec, int iovec_count, globus_size_t
    waitforbytes, globus_xio_data_descriptor_t data_desc,
    globus_xio_iovec_callback_t cb, void *user_arg)
globus_result_t globus_xio_writev (globus_xio_handle_t handle,
    globus_xio_iovec_t *iovec, int iovec_count, globus_size_t
    waitforbytes, globus_size_t *nbytes, globus_xio_data_descriptor_t
    data_desc)
globus_result_t globus_xio_register_close (globus_xio_handle_t handle,
    globus_xio_attr_t attr, globus_xio_callback_t cb, void *user_arg)
globus_result_t globus_xio_close (globus_xio_handle_t handle,
    globus_xio_attr_t attr)
globus_result_t globus_xio_handle_create_from_url (globus_xio_handle_t
    *out_h, const char *scheme, globus_xio_attr_t attr, char
    *param_string)
globus_result_t globus_xio_driver_list_to_stack_attr (globus_list_t
    *driver_list, globus_xio_stack_t stack, globus_xio_attr_t attr)
  • globus_xio_driver_list_to_stack_attr — Add a list of driver entries to a stack. 🫶

and then the handle-cntl glow-ups, each one a lil' overload:

globus_result_t globus_xio_handle_cntl (handle, driver,
    GLOBUS_XIO_GET_LOCAL_CONTACT, char **contact_string_out)
globus_result_t globus_xio_handle_cntl (handle, driver,
    GLOBUS_XIO_GET_LOCAL_NUMERIC_CONTACT, char **contact_string_out)
globus_result_t globus_xio_handle_cntl (handle, driver,
    GLOBUS_XIO_GET_REMOTE_CONTACT, char **contact_string_out)
globus_result_t globus_xio_handle_cntl (handle, driver,
    GLOBUS_XIO_GET_REMOTE_NUMERIC_CONTACT, char **contact_string_out)
globus_result_t globus_xio_handle_cntl (handle, driver, GLOBUS_XIO_SEEK,
    globus_off_t offset)
globus_result_t globus_xio_handle_cntl (handle, driver,
    GLOBUS_XIO_SET_STRING_OPTIONS, char *config_string)
globus_result_t globus_xio_handle_cntl (handle, driver,
    GLOBUS_XIO_GET_STRING_OPTIONS, char **config_string)
globus_result_t globus_xio_handle_cntl (handle, driver,
    GLOBUS_XIO_GET_DRIVER_NAME, const char **driver_name)

🌈 Detailed Description 🌈

Globus XIO API. that's it, that's the detailed description, it's giving "confident and concise" 💅

🦋 Typedef Documentation 🦋

typedef void(* globus_xio_accept_callback_t) (globus_xio_server_t server, globus_xio_handle_t handle, globus_result_t result, void *user_arg)

Callback signature for accept. 🎀

when a registered accept operation finishes, the user's function with this signature gets called. that's the whole deal.

Parameters

  • server — The server object on which the accept was registered.
  • handle — The newly created handle that was created by the accept operation. brand new handle just dropped ✨
  • result — A result code indicating the success of the accept operation. GLOBUS_SUCCESS indicates a successful accept.
  • user_arg — A user argument that is threaded from the registration to the callback.

typedef void(* globus_xio_callback_t) (globus_xio_handle_t handle, globus_result_t result, void *user_arg)

globus_xio_callback_t

This callback is used for the open and close asynchronous operations. open and close, but make it async, no cap. 💖

typedef void(* globus_xio_data_callback_t) (globus_xio_handle_t handle, globus_result_t result, globus_byte_t *buffer, globus_size_t len, globus_size_t nbytes, globus_xio_data_descriptor_t data_desc, void *user_arg)

globus_xio_data_callback_t

This callback is used for asynchronous operations that send or receive data. 📨

On EOF, result_t will be of type GLOBUS_XIO_ERROR_EOF 😭

typedef void(* globus_xio_iovec_callback_t) (globus_xio_handle_t handle, globus_result_t result, globus_xio_iovec_t *iovec, int count, globus_size_t nbytes, globus_xio_data_descriptor_t data_desc, void *user_arg)

globus_xio_iovec_callback_t

This callback is used for asynchronous operations that send or receive data with an iovec structure. it's the iovec girlies' turn 🌸

On EOF, result_t will be of type GLOBUS_XIO_ERROR_EOF 😭

typedef enum globus_i_xio_op_type_e globus_xio_operation_type_t

Operation types 🔥

An enumeration of operation types. Used in the timeout callback to indicate what operation typed timedout. so when something times out, this tells you which something. iykyk.

typedef void(* globus_xio_server_callback_t) (globus_xio_server_t server, void *user_arg)

Server callback signature. 👑

This is the generic server callback signature. It is currently only used for the register close operation.

typedef globus_bool_t(* globus_xio_timeout_callback_t) (globus_xio_handle_t handle, globus_xio_operation_type_t type, void *user_arg)

The timeout callback function signature. ⏰

Parameters

  • handle — The handle the handle on which the timeout operation was requested.
  • type — The type of operation that timed out: GLOBUS_XIO_OPERATION_OPEN GLOBUS_XIO_OPERATION_CLOSE GLOBUS_XIO_OPERATION_READ GLOBUS_XIO_OPERATION_WRITE
  • user_arg — A user arg threaded through to the callback.

okay that's part 1 bestie, drink some water, part 2 is coming and we are NOT done 💜

🦋 Enumeration Type Documentation 🦋

okay so this whole section is XIO handing you the little menus of magic numbers 💫 an enum is just the polite way of saying "hey driver, do this specific thing" instead of making you type a raw int like a caveman. it's giving organized. it's giving i-have-a-named-constant-for-that.

🌸 enum globus_i_xio_op_type_e 🌸

Operation types.

An enumeration of operation types. Used in the timeout callback to indicate what operation typed timedout.

not me pointing out that "timedout" is written as one word there — that's the docs' spelling, not a typo i introduced, and i am NOT touching it 💅

🎀 enum globus_xio_handle_cmd_t 🎀

doxygen varargs filter stuff Common driver handle cntls.

literally that's the description, bestie, i don't make the rules, i just relay them with love 🫶

Enumerator

  • GLOBUS_XIO_GET_LOCAL_CONTACT — See usage for: globus_xio_handle_cntl
  • GLOBUS_XIO_GET_LOCAL_NUMERIC_CONTACT — See usage for: globus_xio_handle_cntl
  • GLOBUS_XIO_GET_REMOTE_CONTACT — See usage for: globus_xio_handle_cntl
  • GLOBUS_XIO_GET_REMOTE_NUMERIC_CONTACT — See usage for: globus_xio_handle_cntl
  • GLOBUS_XIO_SEEK — See usage for: globus_xio_handle_cntl
  • GLOBUS_XIO_SET_STRING_OPTIONS — See usage for: globus_xio_handle_cntl
  • GLOBUS_XIO_GET_STRING_OPTIONS — See usage for: globus_xio_handle_cntl
  • GLOBUS_XIO_GET_DRIVER_NAME — See usage for: globus_xio_handle_cntl

every single one of these is like "the actual story lives over in globus_xio_handle_cntl", so consider this your little index card, and the real chapter is further down 👇

💖 Function Documentation 💖

okay this is the main character section, the one you actually came here for. buckle up, we're going function by function, and i am keeping every single parameter, every ..., every double space, all of it. no cap. ✨

🦋 globus_result_t globus_xio_attr_cntl (globus_xio_attr_t attr, globus_xio_driver_t driver, int cmd, ...) 🦋

globus_result_t globus_xio_attr_cntl (globus_xio_attr_t attr,
    globus_xio_driver_t driver, int cmd,  ...)

Manipulate the values associated in the attr.

This function provides a means to access the attr structure. What exactly this function does is determined by the value in the parameter cmd and the value of the parameter driver. When the driver parameter is NULL it indicates that this function applies to general Globus XIO values. If it is not NULL it indicates that the function will effect driver specific values. Each driver is responsible for defining its own enumeration of values for cmd and the var args associated with that command.

Parameters

  • attr — the attribute structure to be manipulated.
  • driver — This parameter indicates which driver the user would like to perform the requested operation. If this parameter is NULL this request will be scoped to general attribute functions.
  • cmd — an enum that determines what specific operation the user is requesting. Each driver will determine the value for this enumeration.
so like, this is the "one function to rule them all" situation. the driver writes the menu, you order off it. the NULL driver is the "general vibes" lane 💅

🌸 globus_result_t globus_xio_attr_copy (globus_xio_attr_t * dst, globus_xio_attr_t src) 🌸

globus_result_t globus_xio_attr_copy (globus_xio_attr_t * dst,
    globus_xio_attr_t src)

Copy an attribute structure.

that's it, that's the whole description, and honestly? iconic. short. efficient. it copies the attr. slay. ✨

🎀 globus_result_t globus_xio_attr_destroy (globus_xio_attr_t attr) 🎀

globus_result_t globus_xio_attr_destroy (globus_xio_attr_t attr)

Clean up resources associated with an attribute.

Parameters

  • attr — Upon completion of this function all resources associated with this structure will returned to the system and the attr will no longer be valid.
bestie when i say "no longer be valid" i mean it is DONE. don't touch it after. it's in its retirement era and it does not want to hear from you 💀

🌈 globus_result_t globus_xio_attr_init (globus_xio_attr_t * attr) 🌈

globus_result_t globus_xio_attr_init (globus_xio_attr_t * attr)

Initialize a Globus XIO attribute.

Parameters

  • attr — upon return from this function this out parameter will be initialized. Once the user is finished with the attribute they should make sure they destroy it in order to free resources associated with it.
so the lifecycle is init → use it → destroy. it's a whole glow-up arc and the destroy is the graduation 🎓

⭐ globus_result_t globus_xio_close (globus_xio_handle_t handle, globus_xio_attr_t attr) ⭐

globus_result_t globus_xio_close (globus_xio_handle_t handle,
    globus_xio_attr_t attr)

Blocking close

yep. that's the description. "Blocking close." two words. it will block. you will wait. the handle will close. we move 💅

🦋 globus_result_t globus_xio_data_descriptor_cntl (globus_xio_data_descriptor_t data_desc, globus_xio_driver_t driver, int cmd, ...) 🦋

globus_result_t globus_xio_data_descriptor_cntl
    (globus_xio_data_descriptor_t data_desc, globus_xio_driver_t driver, int
    cmd,  ...)

Touch driver specific data in data descriptors

This function allows the user to communicate directly with a driver in association with a data descriptors. The driver defines what operations can be preformed.

"preformed" — again, that is exactly what the docs say, and i am a faithful narrator, so it stays. also yes: the driver decides what's on the menu here too. cntl functions are all just "ask the driver, it knows" 🌸

🎀 globus_result_t globus_xio_data_descriptor_destroy (globus_xio_data_descriptor_t data_desc) 🎀

globus_result_t globus_xio_data_descriptor_destroy
    (globus_xio_data_descriptor_t data_desc)

clean up a data descriptor.

lowercase and everything, because the docs said it lowercase, and i respect the docs' lowercase choices 🫶

💜 globus_result_t globus_xio_data_descriptor_init (globus_xio_data_descriptor_t * data_desc, globus_xio_handle_t handle) 💜

globus_result_t globus_xio_data_descriptor_init
    (globus_xio_data_descriptor_t * data_desc, globus_xio_handle_t handle)

Initialize a data descriptor

Parameters

  • data_desc — An out parameter. The data descriptor to be initialized.
  • handle — The handle this data descriptor will be used with. This parameter is require in order to optimize the code handling the data descriptors use.
yes, "is require". we are all just vibing with the typos at this point, and honestly? relatable 😭 the important bit is: you hand it the handle because it uses that to optimize, so don't be out here passing random nonsense.

🔥 globus_result_t globus_xio_driver_list_to_stack_attr (globus_list_t * driver_list, globus_xio_stack_t stack, globus_xio_attr_t attr) 🔥

globus_result_t globus_xio_driver_list_to_stack_attr (globus_list_t *
    driver_list, globus_xio_stack_t stack, globus_xio_attr_t attr)

Add a list of driver entries to a stack. This function walks a list of globus_xio_driver_list_ent_t * values passed as the driver_list parameter, and pushes them onto the XIO stack passed as the stack parameter and sets attributes for those drivers in the attr passed as the attr parameter to this function.

Parameters

  • driver_list — A list of driver list entries in stack order (transport, followed by transform). Each entry may contain a option string for attributes to set for this driver.
  • stack — A pointer to an XIO stack which will have the drivers pushed onto. It must be previously initialized by calling globus_xio_stack_init(). This function does not overwrite the stack, so the drivers passed in the driver list will be pushed on top of any existing drivers in the stack.
  • attr — A pointer to an XIO attribute which will have the driver-specific string options set on it, after the drivers are pushed onto the stack. The opts field of the list entries are passed to the GLOBUS_XIO_SET_STRING_OPTIONS attr control function. This value must be previously initialized by calling globus_xio_attr_init(). Errors from the attr control function are ignored.

Returns

If the driver can not be pushed onto the stack, an error result is returned; otherwise, GLOBUS_SUCCESS. If an error occurs, some of the entries MAY be pushed on to the stack and some attributes may have been set in the attr. Both should be destroyed by the caller.

okay this one is the "build me a whole stack from a list" baddie 👑 and listen — that MAY in caps is doing heavy lifting. if it errors out halfway, some stuff might already be pushed and some attrs might already be set, and it is on YOU to clean both up. it does not roll back for you. be responsible bestie, destroy your things 💅

🌟 globus_result_t globus_xio_handle_cntl (globus_xio_handle_t handle, globus_xio_driver_t driver, int cmd, ...) 🌟

globus_result_t globus_xio_handle_cntl (globus_xio_handle_t handle,
    globus_xio_driver_t driver, int cmd,  ...)

Touch driver specific information in a handle object.

This function allows the user to communicate directly with a driver in association with a handle object. The driver defines what operations can be preformed.

pass the driver to control a specific driver pass NULL for driver for XIO specific cntls pass GLOBUS_XIO_QUERY for driver to try each driver in order until success

okay THIS is the big one, the one every enumerator up top was pointing at 🌈 the three-mode vibe check: - hand it a real driver → you're talking to that driver - hand it NULL → you're in XIO-specific cntl territory - hand it GLOBUS_XIO_QUERY → it just goes down the line trying each driver in order until something works. main character energy, it does NOT give up ✨

🎀 globus_result_t globus_xio_handle_cntl (handle , driver , GLOBUS_XIO_GET_DRIVER_NAME , const char ** driver_name) 🎀

globus_result_t globus_xio_handle_cntl (handle , driver ,
    GLOBUS_XIO_GET_DRIVER_NAME , const char ** driver_name)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Set the driver specific configuration string. The format of the string is defined by the driver. It is typically a set of key=value pairs

Parameters

  • driver_name — The driver name.
yes, the description says "Set the driver specific configuration string" on the function literally named GET the driver name. that is what the docs say. i am simply the messenger and the messenger is obsessed with accuracy 💅

🌸 globus_result_t globus_xio_handle_cntl (handle , driver , GLOBUS_XIO_GET_LOCAL_CONTACT , char ** contact_string_out) 🌸

globus_result_t globus_xio_handle_cntl (handle , driver ,
    GLOBUS_XIO_GET_LOCAL_CONTACT , char ** contact_string_out)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Get local connection info.

Parameters

  • contact_string_out — A pointer to a contact string for the local end of a connected handle. Where possible, it will be in symbolic form (FQDN).

The user must free the returned string.

🚨 bestie the free is on YOU. it hands you a string, you take it to the free like a grown-up. do not leak it, it's not cute. 🫶

See also

globus_xio_server_get_contact_string()

🎀 globus_result_t globus_xio_handle_cntl (handle , driver , GLOBUS_XIO_GET_LOCAL_NUMERIC_CONTACT , char ** contact_string_out) 🎀

globus_result_t globus_xio_handle_cntl (handle , driver ,
    GLOBUS_XIO_GET_LOCAL_NUMERIC_CONTACT , char ** contact_string_out)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Get local connection info.

Parameters

  • contact_string_out — A pointer to a contact string for the local end of a connected handle. Where possible, it will be in numeric form. (IP)

The user must free the returned string.

same local info as above, but numeric. IP instead of FQDN. no names, just numbers, mysterious and direct ✨ and again: free the string 💀

💜 globus_result_t globus_xio_handle_cntl (handle , driver , GLOBUS_XIO_GET_REMOTE_CONTACT , char ** contact_string_out) 💜

globus_result_t globus_xio_handle_cntl (handle , driver ,
    GLOBUS_XIO_GET_REMOTE_CONTACT , char ** contact_string_out)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Get remote connection info.

Parameters

  • contact_string_out — A pointer to a contact string for the remote end of a connected handle. Where possible, it will be in symbolic form (FQDN).

The user must free the returned string.

remote this time, not local. symbolic again, so FQDN. and yeah — you already know — free it. 🍓

🌈 globus_result_t globus_xio_handle_cntl (handle , driver , GLOBUS_XIO_GET_REMOTE_NUMERIC_CONTACT , char ** contact_string_out) 🌈

globus_result_t globus_xio_handle_cntl (handle , driver ,
    GLOBUS_XIO_GET_REMOTE_NUMERIC_CONTACT , char ** contact_string_out)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Get remote connection info.

Parameters

  • contact_string_out — A pointer to a contact string for the remote end of a connected handle. Where possible, it will be in numeric form. (IP)

The user must free the returned string.

the full set! local-symbolic, local-numeric, remote-symbolic, remote-numeric. a little quartet of contact strings 🎶 and all four of them want to be freed by you. that's the deal. 💅

⭐ globus_result_t globus_xio_handle_cntl (handle , driver , GLOBUS_XIO_GET_STRING_OPTIONS , char ** config_string) ⭐

globus_result_t globus_xio_handle_cntl (handle , driver ,
    GLOBUS_XIO_GET_STRING_OPTIONS , char ** config_string)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Set the driver specific configuration string. The format of the string is defined by the driver. It is typically a set of key=value pairs

Parameters

  • config_string — The driver specific parameter string.
yes. the GET version's blurb says "Set". we've been over this. the docs contain multitudes and i contain accuracy 😭 note this one takes char ** config_string — double pointer, bestie.

🦋 globus_result_t globus_xio_handle_cntl (handle , driver , GLOBUS_XIO_SEEK , globus_off_t offset) 🦋

globus_result_t globus_xio_handle_cntl (handle , driver , GLOBUS_XIO_SEEK ,
    globus_off_t offset)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Reposition read/write offset.

Parameters

  • offset — Specify the desired offset.
seek! the "scuse me, i'd like to read/write from over there instead" move. the offset is a globus_off_t, and it is exactly where you wanna be 📍

🎀 globus_result_t globus_xio_handle_cntl (handle , driver , GLOBUS_XIO_SET_STRING_OPTIONS , char * config_string) 🎀

globus_result_t globus_xio_handle_cntl (handle , driver ,
    GLOBUS_XIO_SET_STRING_OPTIONS , char * config_string)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Set the driver specific configuration string. The format of the string is defined by the driver. It is typically a set of key=value pairs

Parameters

  • config_string — The driver specific parameter string.
and here's the SET one, and THIS time it takes char * config_string — single pointer. one star, not two. the way that GET and SET differ by a whole pointer level is lowkey the funniest little detail and i will not be explaining further 🌸

🔥 globus_result_t globus_xio_handle_create (globus_xio_handle_t * handle, globus_xio_stack_t stack) 🔥

globus_result_t globus_xio_handle_create (globus_xio_handle_t * handle,
    globus_xio_stack_t stack)

Initialize a handle for client opens

This function will initialize a handle for active opens (client side connections).

active opens! client side! this is you reaching OUT into the world to make a connection, not sitting around waiting for one. go get it, main character 👑

✨ globus_result_t globus_xio_handle_create_from_url (globus_xio_handle_t * out_h, const char * scheme, globus_xio_attr_t attr, char * param_string) ✨

globus_result_t globus_xio_handle_create_from_url (globus_xio_handle_t *
    out_h, const char * scheme, globus_xio_attr_t attr, char * param_string)

Initializes a handle based on the scheme given.

that's the whole blurb, bestie — short and sweet and it's giving "the details are elsewhere" 💫 it takes your out_h, your scheme, your attr and your param_string, and it makes you a handle out of it.

  • out_h — an uninitialized handle that gets initialized inside this function to match whatever scheme you handed it. This is the handle you're gonna use for literally every I/O operation after. 💅
  • scheme — a string with the protocol your handle should be initialized to. Can be a bare protocol like "http", or a full scheme like "http://www.example.com". Either way, slay.
  • attr — the attribute used for setting the parameter string. It gets initialized by the function. Can be NULL if you're not doing attributes (no shame, bestie).
  • param_string — a string of attributes to set for the drivers associated with the scheme. Format is "protocol1:option1=value1;option2=value2,protocol2:option1=value1;option2=value2". Can be NULL if attributes aren't your thing.

globus_result_t globus_xio_open (globus_xio_handle_t handle, const char * contact_string, globus_xio_attr_t attr)

The blocking open. Like the async one but it just... sits there and waits. Main character energy honestly.

globus_result_t globus_xio_read (globus_xio_handle_t handle, globus_byte_t * buffer, globus_size_t buffer_length, globus_size_t waitforbytes, globus_size_t * nbytes, globus_xio_data_descriptor_t data_desc)

Reads data from a handle. That's it, that's the vibe. 📖

globus_result_t globus_xio_readv (globus_xio_handle_t handle, globus_xio_iovec_t * iovec, int iovec_count, globus_size_t waitforbytes, globus_size_t * nbytes, globus_xio_data_descriptor_t data_desc)

Reads data from a handle into a globus_xio_iovec_t (which is a struct iovec). Scatter-read girlies rise ✨

globus_result_t globus_xio_register_close (globus_xio_handle_t handle, globus_xio_attr_t attr, globus_xio_callback_t cb, void * user_arg)

Close a handle.

This one straight-up serves as the destroy for the handle. The absolute second the operation completes (i.e. the callback fires), the handle is destroyed. Gone. Poof. 💀

Parameters

  • handle — the handle that's getting closed.
  • attr — how-to-close attribute.
  • cb — the function called when the close operation completes.
  • user_arg — a user pointer that gets threaded all the way through to the callback.

globus_result_t globus_xio_register_open (globus_xio_handle_t handle, const char * contact_string, globus_xio_attr_t attr, globus_xio_callback_t cb, void * user_arg)

Open a handle.

Creates an open handle based on the state living inside the given stack.

Real talk though: you can NOT perform any operation on a handle until it's been initialized and then opened. And if the handle you pass in is already open, the info contained in that handle gets destroyed. Rip to the old state 🙈

Parameters

  • handle — the handle created with globus_xio_handle_create() or globus_xio_server_register_accept() that is to be opened.
  • attr — how-to-open attribute. can be NULL.
  • cb — the function to be called when the open operation completes.
  • user_arg — a user pointer that will be threaded through to the callback.
  • contact_string — a url describing the resource. NULL is allowed. Drivers interpret the various parts of this url as described in their documentation. There's also an alternative form: if contact_string doesn't specify a scheme (like http://) and it contains a ':', it gets parsed as a host:port pair. If it does NOT contain a ':', it gets parsed as the path.

the following are examples of valid formats:

<path to file>
host-name ":" <service or port>
"file:" <path to file>
<scheme> "://" [ "/" [ <path to resource> ]  ]
<scheme> "://" location [ "/" [ <path to resource> ] ]
  location:
      [ auth-part ] host-part
  auth-part:
      <user> [ ":" <password> ] "@"
  host-part:
      [ "<" <subject> ">" ] host-name [ ":" <port or service> ]
  host-name:
      <hostname> | <dotted quad> | "[" <ipv6 address> "]"

Except for use as the above delimiters, the following special characters MUST be encoded with the %HH format where H == hex char. No exceptions bestie, I don't make the rules:

  • "/" and "@" in location except subject
  • "<" and ">" in location
  • ":" everywhere except ipv6 address and subject
  • "%" everywhere (can be encoded with %HH or %%)

globus_result_t globus_xio_register_read (globus_xio_handle_t handle, globus_byte_t * buffer, globus_size_t buffer_length, globus_size_t waitforbytes, globus_xio_data_descriptor_t data_desc, globus_xio_data_callback_t cb, void * user_arg)

Reads data from a handle. 🌸

globus_result_t globus_xio_register_readv (globus_xio_handle_t handle, globus_xio_iovec_t * iovec, int iovec_count, globus_size_t waitforbytes, globus_xio_data_descriptor_t data_desc, globus_xio_iovec_callback_t cb, void * user_arg)

Reads data from a handle into a globus_xio_iovec_t (aka struct iovec). 🦋

globus_result_t globus_xio_register_write (globus_xio_handle_t handle, globus_byte_t * buffer, globus_size_t buffer_length, globus_size_t waitforbytes, globus_xio_data_descriptor_t data_desc, globus_xio_data_callback_t cb, void * user_arg)

Writes data to a handle. ✍️

globus_result_t globus_xio_register_writev (globus_xio_handle_t handle, globus_xio_iovec_t * iovec, int iovec_count, globus_size_t waitforbytes, globus_xio_data_descriptor_t data_desc, globus_xio_iovec_callback_t cb, void * user_arg)

Writes data to a handle from a globus_xio_iovec_t (aka struct iovec). 🎀

globus_result_t globus_xio_server_accept (globus_xio_handle_t * out_handle, globus_xio_server_t server)

Accept a connection.

This function accepts a connection on the given server object, and the parameter out_handle will be valid if the function returns successfully. (So like. check your return value, bestie.) 👑

globus_result_t globus_xio_server_close (globus_xio_server_t server)

A blocking server close. It blocks. That's the whole personality. 💤

globus_result_t globus_xio_server_cntl (globus_xio_server_t server, globus_xio_driver_t driver, int cmd, ...)

Touch driver specific information in a server object.

This lets you communicate directly with a driver, in association with a server object. The driver is the one who defines what operations can be performed. iykyk 🫶

globus_result_t globus_xio_server_create (globus_xio_server_t * server, globus_xio_attr_t server_attr, globus_xio_stack_t stack)

Create a server object.

This one lets you create a server object, which you can then use to accept connections. Networking era unlocked 🌈

Parameters

  • server — an out parameter. Once the function successfully returns, this points to a valid server object.
  • server_attr — an attribute structure used to alter the default server initialization. This is mostly used in a driver-specific manner. can be NULL.
  • stack — the stack. (Yep, that's the whole description. Iconic brevity honestly.)

globus_result_t globus_xio_server_get_contact_string (globus_xio_server_t server, char ** contact_string)

get contact string

Lets you grab the contact string for a server. That string can then be used as the contact string for the client side. Cute little handoff 🤝

Parameters

  • server — an initialized server handle created with globus_xio_server_create().
  • contact_string — an out variable. Will point to a newly allocated string on success. must be freed by the caller. Don't you dare leak it 🚨

globus_result_t globus_xio_server_register_accept (globus_xio_server_t server, globus_xio_accept_callback_t cb, void * user_arg)

Asynchronous accept.

Posts a nonblocking accept. Once the operation completes, the user function pointed to by the parameter cb gets called. ⚡

globus_result_t globus_xio_server_register_close (globus_xio_server_t server, globus_xio_server_callback_t cb, void * user_arg)

post a close on a server object

Registers a close operation on a server. When the user function pointed to by parameter cb is called, the server object is closed. periodt 💅

globus_result_t globus_xio_stack_copy (globus_xio_stack_t * dst, globus_xio_stack_t src)

Copy a stack object. Duplicate it. Twin era. 👯

globus_result_t globus_xio_stack_destroy (globus_xio_stack_t stack)

Destroy a stack object. 💥

globus_result_t globus_xio_stack_init (globus_xio_stack_t * stack, globus_xio_attr_t stack_attr)

Initialize a stack object. Fresh start, clean slate ✨

globus_result_t globus_xio_stack_push_driver (globus_xio_stack_t stack, globus_xio_driver_t driver)

Push a driver onto a stack.

No attrs are associated with a driver, jsyk. The stack represents the ordered list of transform drivers plus exactly 1 transport driver. And the transport driver must be pushed on first. Order matters, bestie 🎯

globus_result_t globus_xio_write (globus_xio_handle_t handle, globus_byte_t * buffer, globus_size_t buffer_length, globus_size_t waitforbytes, globus_size_t * nbytes, globus_xio_data_descriptor_t data_desc)

Write data to a handle. ✏️

globus_result_t globus_xio_writev (globus_xio_handle_t handle, globus_xio_iovec_t * iovec, int iovec_count, globus_size_t waitforbytes, globus_size_t * nbytes, globus_xio_data_descriptor_t data_desc)

Write data to a handle from a globus_xio_iovec_t (aka struct iovec). 🍓

Author

Generated automatically by Doxygen for globus_xio from the source code. (Not a human, not a bestie, just a doc generator doing its little thing. Respect.) 🧚

And that's the whole page, bestie!! We did it 🎉 This was globus_xio Version 6.6, the GLOBUS_XIO_API(3) manual, and yeah — it's giving very much "generated by Doxygen, documented with love." Go forth and open some handles. Slay 💖🌸👑

📦 where this page comes from