globus_xio_driver(3)

📦

version 6.6 · 7 versions

6.6 · fedora 44, ubuntu resolute, ubuntu stonking (latest)
6.6 · epel 9
6.6 · epel 10
6.5 · ubuntu jammy
6.6 · fedora 43
6.6 · debian bookworm
6.6 · debian trixie, ubuntu noble, ubuntu questing

, in fedora 44, ubuntu resolute, ubuntu stonking

✨ NAME ✨

globus_xio_driver — Globus XIO Driver. 💖

(straight from the globus_xio_driver(3) page, Library Functions Manual, and yes bestie this is the C API, so hydrate before reading)

globus_xio_driver — Globus XIO Driver.
- — Globus XIO Driver.

🦋 SYNOPSIS 🦋

🌸 Topics 🌸

💅 Driver Programming: String options 💅

Driver Programming: String options — Driver Programming: String options. (it’s giving self-reference, we love an icon who contains multitudes)

🎀 Typedefs 🎀

Okay so the typedefs are:

globus_xio_driver_callback_t — Open and Close Callback Signature. 💫

typedef void(* globus_xio_driver_callback_t) (globus_xio_operation_t op,
    globus_result_t result, void *user_arg)

globus_xio_driver_data_callback_t — no blurb, just vibes.

typedef void(* globus_xio_driver_data_callback_t)
    (globus_xio_operation_t op, globus_result_t result, globus_size_t
    nbytes, void *user_arg)

globus_xio_driver_attr_init_t — no blurb.

typedef globus_result_t(* globus_xio_driver_attr_init_t) (void
    **out_driver_attr)

globus_xio_driver_attr_copy_t — no blurb.

typedef globus_result_t(* globus_xio_driver_attr_copy_t) (void **dst,
    void *src)

globus_xio_driver_attr_destroy_t — no blurb.

typedef globus_result_t(* globus_xio_driver_attr_destroy_t) (void
    *driver_attr)

globus_xio_driver_attr_cntl_t — no blurb.

typedef globus_result_t(* globus_xio_driver_attr_cntl_t) (void
    *driver_attr, int cmd, va_list ap)

globus_xio_driver_server_init_t — no blurb.

typedef globus_result_t(* globus_xio_driver_server_init_t) (void
    *driver_attr, const globus_xio_contact_t *contact_info,
    globus_xio_operation_t op)

globus_xio_driver_server_destroy_t — no blurb.

typedef globus_result_t(* globus_xio_driver_server_destroy_t) (void
    *driver_server)

globus_xio_driver_server_accept_t — no blurb.

typedef globus_result_t(* globus_xio_driver_server_accept_t) (void
    *driver_server, globus_xio_operation_t op)

globus_xio_driver_server_cntl_t — no blurb.

typedef globus_result_t(* globus_xio_driver_server_cntl_t) (void
    *driver_server, int cmd, va_list ap)

globus_xio_driver_link_destroy_t — no blurb.

typedef globus_result_t(* globus_xio_driver_link_destroy_t) (void
    *driver_link)

globus_xio_driver_transform_open_t — Open a handle. 🫶

typedef globus_result_t(* globus_xio_driver_transform_open_t) (const
    globus_xio_contact_t *contact_info, void *driver_link, void
    *driver_attr, globus_xio_operation_t op)

globus_xio_driver_transport_open_t — Open a handle. 🫶

typedef globus_result_t(* globus_xio_driver_transport_open_t) (const
    globus_xio_contact_t *contact_info, void *driver_link, void
    *driver_attr, globus_xio_operation_t op)

globus_xio_driver_handle_cntl_t — no blurb.

typedef globus_result_t(* globus_xio_driver_handle_cntl_t) (void
    *handle, int cmd, va_list ap)

globus_xio_driver_close_t — Close a handle. 💅

typedef globus_result_t(* globus_xio_driver_close_t) (void
    *driver_specific_handle, void *driver_attr, globus_xio_operation_t
    op)

globus_xio_driver_read_t — no blurb.

typedef globus_result_t(* globus_xio_driver_read_t) (void
    *driver_specific_handle, const globus_xio_iovec_t *iovec, int
    iovec_count, globus_xio_operation_t op)

globus_xio_driver_write_t — no blurb.

typedef globus_result_t(* globus_xio_driver_write_t) (void
    *driver_specific_handle, const globus_xio_iovec_t *iovec, int
    iovec_count, globus_xio_operation_t op)

🌈 Functions 🌈

globus_xio_driver_set_server_pre_init — Server Pre-Init. 🛠️

globus_result_t globus_xio_driver_set_server_pre_init
    (globus_xio_driver_t driver, globus_xio_driver_server_init_t
    server_pre_init_func)

globus_xio_driver_handle_cntl — no blurb.

globus_result_t globus_xio_driver_handle_cntl
    (globus_xio_driver_handle_t handle, globus_xio_driver_t driver, int
    cmd,...)

globus_xio_driver_finished_accept — no blurb.

void globus_xio_driver_finished_accept (globus_xio_operation_t op, void
    *driver_link, globus_result_t result)

globus_xio_driver_pass_open — no blurb.

globus_result_t globus_xio_driver_pass_open (globus_xio_operation_t op,
    const globus_xio_contact_t *contact_info,
    globus_xio_driver_callback_t cb, void *user_arg)

globus_xio_driver_finished_open — no blurb.

void globus_xio_driver_finished_open (void *driver_handle,
    globus_xio_operation_t op, globus_result_t result)

globus_xio_driver_operation_create — no blurb.

globus_result_t globus_xio_driver_operation_create
    (globus_xio_operation_t *operation, globus_xio_driver_handle_t
    handle)

globus_xio_driver_operation_is_blocking — no blurb.

globus_bool_t globus_xio_driver_operation_is_blocking
    (globus_xio_operation_t operation)

globus_xio_driver_pass_close — Pass the close operation down the driver stack. ⬇️

globus_result_t globus_xio_driver_pass_close (globus_xio_operation_t op,
    globus_xio_driver_callback_t cb, void *callback_arg)

globus_xio_driver_finished_close — no blurb.

void globus_xio_driver_finished_close (globus_xio_operation_t op,
    globus_result_t result)

globus_xio_driver_pass_read — no blurb.

globus_result_t globus_xio_driver_pass_read (globus_xio_operation_t op,
    globus_xio_iovec_t *iovec, int iovec_count, globus_size_t wait_for,
    globus_xio_driver_data_callback_t cb, void *user_arg)

globus_xio_driver_finished_read — no blurb.

void globus_xio_driver_finished_read (globus_xio_operation_t op,
    globus_result_t result, globus_size_t nread)

globus_xio_driver_set_eof_received — no blurb.

void globus_xio_driver_set_eof_received (globus_xio_operation_t op)

globus_xio_driver_eof_received — no blurb.

globus_bool_t globus_xio_driver_eof_received (globus_xio_operation_t op)

globus_xio_driver_pass_write — no blurb.

globus_result_t globus_xio_driver_pass_write (globus_xio_operation_t op,
    globus_xio_iovec_t *iovec, int iovec_count, globus_size_t wait_for,
    globus_xio_driver_data_callback_t cb, void *user_arg)

globus_xio_driver_finished_write — no blurb.

void globus_xio_driver_finished_write (globus_xio_operation_t op,
    globus_result_t result, globus_size_t nwritten)

globus_xio_driver_merge_operation — no blurb.

globus_result_t globus_xio_driver_merge_operation
    (globus_xio_operation_t top_op, globus_xio_operation_t bottom_op)

💖 Detailed Description 💖

Globus XIO Driver.

Globus XIO brings a whole driver stack concept into its API. Inside globus_xio, every single I/O operation has to happen on a globus_xio handle. Each handle has a stack of drivers attached to it. A driver is a modular little piece of code that implements the globus_xio driver interface. Its whole purpose? Manipulate the data the user passed in, some way, somehow. Every driver in a stack serves its own unique purpose.

I/O operations hop from driver to driver, starting at the top of the stack and ending at the bottom. When the bottom-layer driver is done with the operation, it signals globus_xio that it’s completed. Completion notification then flows all the way back up to the top of the driver stack. periodt. ✨

🚀 Driver Types 🚀

Transport driver: A transport driver is responsible for data communication. For example, a TCP or UDP driver would transmit data via network sockets, or a file driver would write data to a file.

There must be exactly one transport driver in a stack, and it has to be at the bottom. A transport driver never passes an operation to another driver in the stack. Instead, this type of driver relies on globus_xio system functions to implement data operations.

Transform driver: A transform driver is any intermediate driver in the stack. A transform driver relies on some other drivers on the driver stack to perform the data transport operation. An example would be a transform driver that implements a network protocol such as http. This driver would frame and parse messages, but it would rely on other drivers in the XIO stack.

This allows additional transforms to happen in the XIO stack, such as layering the http protocol on top of an SSL protocol driver before transmitting the data via TCP. 👑

👑 Driver API 👑

The Globus XIO Driver API is a set of functions and interfaces that let a developer create an XIO driver. To create a driver, the user must implement all of the interface functions in the driver specification. There is also a set of functions provided to assist the driver author in implementing a driver.

🌟 Quick Start 🌟

For basic driver needs, the developer will have to pay attention to a few structures and concepts.

globus_xio_operation_t — This structure represents a request for an operation. If the driver can service the operation, it does so and then calls the appropriate finished function. If the driver cannot completely service the operation, it can pass it to the next driver in the stack. As soon as the operation structure is either finished or passed, it is no longer valid for use in any other function.
globus_xio_driver_handle_t — A globus_xio_driver_handle_t represents an open handle to the driver stack for XIO. The driver obtains a driver_handle by calling globus_xio_operation_get_driver_handle(). The driver_handle allows the user to do some complex things that will be described later.

🦄 Typical Sequence: 🦄

Here is a typical sequence of events for a globus_xio transform driver. All operations are initiated either by the application calling a function in the Globus XIO API, or from a driver above the transform driver in the stack passing an operation to this driver.

Open — XIO calls the globus_xio_driver_transform_open_t function of the driver, passing it the operation and, in the case of a passive open, the link from a server accept. The driver typically allocates a private data structure containing the state it wishes to associate with this handle, and passes this along with a callback function pointer to globus_xio_driver_pass_open(). This allows the other drivers in the XIO stack to continue to process the operation.

After the lower drivers in the stack have completed processing the open, they will call globus_xio_driver_finished_open(), which will in turn call the callback function which the driver passed as a parameter to globus_xio_driver_pass_open(). The driver then does any post-open operation needed, and then finishes the operation by calling globus_xio_driver_finished_open(), passing the private state data as the driver_handle parameter. This state data will be passed to future operation implementations done with this handle.

Read/Write — XIO calls the driver’s globus_xio_driver_read_t or globus_xio_driver_write_t function with an operation as a parameter and the state date from the globus_xio_driver_finished_open() call. The driver then transforms the data if necessary and then calls the globus_xio_driver_pass_read() or globus_xio_driver_pass_write() which passes the operation down the XIO driver stack. When the driver below it on the XIO stack calls globus_xio_driver_finished_read() or globus_xio_driver_finished_write(), the callback which was passed is invoked. In that callback, the driver should itself call globus_xio_driver_finished_read() or globus_xio_driver_finished_write() to indicate completion.
Close — XIO calls the close interface function, passing an operation and the private driver state. The driver will call globus_xio_driver_pass_close() passing it the operation. When the close callback is received the driver calls globus_xio_driver_finished_close() passing it the operation. At this point, the driver typically frees its private data, as the handle is no longer valid.

🧚 Globus XIO Attributes 🧚

Attributes provide a way to pass additional metadata to driver operations. Most Globus XIO API functions include an attribute parameter. Each driver implements its own set of attribute handling function. To implement attributes, a driver must provide functions of these types:

globus_xio_driver_attr_init_t
globus_xio_driver_attr_copy_t
globus_xio_driver_attr_cntl_t
globus_xio_driver_attr_destroy_t

Pointers to these functions are associated with the driver by calling globus_xio_driver_set_attr

✨ Advanced Driver Programming ✨

okay bestie so that typical driver implementation we just talked about? that's the vanilla version. it's cute, it works, it's giving "hello world but make it I/O" 💅 but globus_xio does not gatekeep — driver authors can do way more advanced stuff, like kicking off operations on their own. no waiting around for XIO to call you first, you're the main character now. periodt. 👑

🦋 Read Ahead 🦋

so here's the tea ☕ — once a handle is open, a driver can just... create operation structures from it. iconic. and then it can request I/O from the driver stack before it even receives a call to its own I/O interface functions. that's the whole read-ahead moment, it's literally just you being proactive and fetching data early. it's giving "reading ahead in the group chat before you reply" fr fr 📖✨

and here's exactly how you do it, step by step, no cap:

Obtain a driver handle from the open operation by calling globus_xio_operation_get_driver_handle(). yes, the open operation hands it to you, that's the whole point. 🫶
Create an operation by calling globus_xio_driver_operation_create() and pass it the driver_handle from the previous step. gotta feed it the handle, it's hungry. 🍓
call globus_xio_driver_pass_read() using this operation. then when the read callback comes through, the driver saves the returned data in its private data and then calls globus_xio_driver_finished_read() on the operation. stash the goods, close the loop, slay. 💖
When XIO calls the driver's read interface function, the driver can immediately call globus_xio_driver_finished_read() — but only after updating the iovec structure with the data it had previously read. like, the iovec needs the receipts first, then you finish. order matters bestie, do not skip the iovec update 😭

fr this is the glow-up move: you already read the data, so when XIO finally comes knocking, you're not scrambling — you just hand it over and finish. efficiency ate and left no crumbs 👑

so yeah, that's read-ahead. you're basically doing your own homework before the teacher assigns it. academic weapon energy 🌈📚

✨ Typedef Documentation ✨

okay so bestie, these are the typedefs that make the XIO driver world go round. each one is like a little contract you sign when you write a driver. let's break them down one by one. 💖

`globus_xio_driver_attr_cntl_t`

   typedef globus_result_t(* globus_xio_driver_attr_cntl_t) (void *driver_attr,
       int cmd, va_list ap)

this one is for getting or setting info in an attr. the cmd parameter is literally telling the driver what the user wants. and the driver is responsible for documenting all the possible values that cmd can be. so like, no gatekeeping, bestie. 📝

Parameters:

driver_attr — the driver specific attr, created by globus_xio_driver_attr_init_t.
cmd — an integer representing what functionality the user is requesting.
ap — variable arguments. These are determined by the driver and the value of cmd.

`globus_xio_driver_attr_copy_t`

   typedef globus_result_t(* globus_xio_driver_attr_copy_t) (void **dst, void
       *src)

when this function gets called, the driver is gonna create a copy of the attr in the src parameter and put it in the dst parameter. it's giving copy-paste energy but for attrs. 💅

`globus_xio_driver_attr_destroy_t`

   typedef globus_result_t(* globus_xio_driver_attr_destroy_t) (void
       *driver_attr)

destroy the driver attr. clean up all resources associated with the attr. like, bye bye, no more attr. 🗑️

`globus_xio_driver_attr_init_t`

   typedef globus_result_t(* globus_xio_driver_attr_init_t) (void
       **out_driver_attr)

create a driver specific attribute. the driver should implement this function to create a driver specific attribute and return it via the out_attr parameter. wait, the parameter is called out_driver_attr but the description says out_attr? we gotta keep it exact. so yeah, return it via out_attr parameter. (iykyk) ✨

`globus_xio_driver_callback_t`

   typedef void(* globus_xio_driver_callback_t) (globus_xio_operation_t op,
       globus_result_t result, void *user_arg)

open and close callback signature. this is the function signature of callbacks for the globus_xio_pass_open() and globus_xio_pass_close() functions. so when you pass open or close, this is the vibe. 🫶

Parameters:

op — the operation structure associated with the open or the close requested operation. the driver should call the appropriate finished operation to clean up this structure.
result — the result of the requested data operation.
user_arg — the user pointer that is threaded through to the callback.

`globus_xio_driver_close_t`

   typedef globus_result_t(* globus_xio_driver_close_t) (void
       *driver_specific_handle, void *driver_attr, globus_xio_operation_t op)

close a handle. this closes a handle. driver implementations should pass the close to the other drivers in the stack by calling globus_xio_pass_close(). also, in the close callback, the driver should clean up the data associated with driver_handle. so like, tidy up, bestie. 🧹

Parameters:

driver_specific_handle — the driver handle to be closed.
driver_attr — a driver specific attr which may be used to alter how a close is performed (e.g. caching drivers).
op — the open operation. When the driver is finished opening the handle, it passes this to globus_xio_driver_finished_close() to return status up the driver stack to the application.

`globus_xio_driver_data_callback_t`

   typedef void(* globus_xio_driver_data_callback_t) (globus_xio_operation_t
       op, globus_result_t result, globus_size_t nbytes, void *user_arg)

data callback interface. this is the function signature of read and write operation callbacks. so when you read or write, this is what gets called. 📖✍️

Parameters:

op — the operation structure associated with the read or write operation request. the driver should call the appropriate finished operation when it receives this operation.
result — the result of the requested data operation.
nbytes — the number of bytes read or written.
user_arg — the user pointer that is threaded through to the callback.

`globus_xio_driver_handle_cntl_t`

   typedef globus_result_t(* globus_xio_driver_handle_cntl_t) (void *handle,
       int cmd, va_list ap)

bestie, listen up: this call must return an GLOBUS_XIO_ERROR_COMMAND error for unsupported command numbers. (use GlobusXIOErrorInvalidCommand(cmd)). and drivers that have reason to support the commands listed at globus_xio_handle_cmd_t should accept the xio generic cmd numbers and their driver specific command number.

⚠️ do NOT implement those handle cntls unless you really are the definitive source. periodt. 🛑

`globus_xio_driver_link_destroy_t`

   typedef globus_result_t(* globus_xio_driver_link_destroy_t) (void
       *driver_link)

destroy a link. the driver should clean up all resources associated with the link when this function is called. so like, no loose ends. 💀

Parameters:

driver_link — the link to be destroyed.

`globus_xio_driver_read_t`

   typedef globus_result_t(* globus_xio_driver_read_t) (void
       *driver_specific_handle, const globus_xio_iovec_t *iovec, int
       iovec_count, globus_xio_operation_t op)

read data from an open handle. this function is called when the user requests to read data from a handle. the driver author shall implement all code needed to for there driver to complete a read operations. (yes, it says "for there driver", we're keeping it exactly.) 📚

Parameters:

driver_specific_handle — the driver handle from which data should be read.
iovec — an io vector pointing to the buffers to be read into.
iovec_count — the number if entries in the io vector. (again, "if" not "of", keeping it exact.)
op — the requested operation. When the driver is finished fulfilling the requested read operation it must use this structure to signal globus_xio that the operation is completed. This is done by calling globus_xio_driver_finished_operation().

`globus_xio_driver_server_accept_t`

   typedef globus_result_t(* globus_xio_driver_server_accept_t) (void
       *driver_server, globus_xio_operation_t op)

accept a server connection. the driver developer should implement this function if their driver handles server operations. once the accept operation completes, the connection is established. the user still has an opportunity to open the link or destroy it. they can query the link for additional information on which to base the decision to open. so like, the ball is in their court. 🏀

Parameters:

driver_server — the server object from which the link connection will be accepted.
op — the requested operation. When the driver is finished accepting the server connection it uses this structure to signal globus_xio that it has completed the operation.

`globus_xio_driver_server_cntl_t`

   typedef globus_result_t(* globus_xio_driver_server_cntl_t) (void
       *driver_server, int cmd, va_list ap)

query a server for information. this function allows a user to request information from a driver specific server handle. so like, asking the server for the tea. ☕

Parameters:

driver_server — the server handle.
cmd — an integer telling the driver what operation to preform on this server handle. (yes, "preform", we keep it.)
ap — variable args.

`globus_xio_driver_server_destroy_t`

   typedef globus_result_t(* globus_xio_driver_server_destroy_t) (void
       *driver_server)

destroy a server. when this function is called the driver should free up all resources associated with a server. so like, server's out, bye. 👋

Parameters:

driver_server — the reference to the internal server that is being declared invalid with this function call.

`globus_xio_driver_server_init_t`

   typedef globus_result_t(* globus_xio_driver_server_init_t) (void
       *driver_attr, const globus_xio_contact_t *contact_info,
       globus_xio_operation_t op)

initialize a server object. the driver developer should implement this function if their driver handles server operations (passive opens). in the TCP driver this function creates a TCP socket and calls listen() on it. unlike all other XIO driver implementation functions, the globus_xio_server_create() function begins at the bottom (transport driver) of the stack, and the globus_xio_driver_pass_server_init() acts like a finished() operation. so it's giving reverse energy. 🔄

Parameters:

driver_attr — a driver-specific attribute. This may be NULL.
contact_info — contact information from the stack below this driver. This is NULL for the transport driver.
op — an op which must be passed to globus_xio_driver_pass_server_init() to pass the server contact information up the XIO driver stack.

Returns:

Returning GLOBUS_SUCCESS for this means that globus_xio_driver_pass_server_init returned success and the driver's server-specific data is initialized.

`globus_xio_driver_transform_open_t`

   typedef globus_result_t(* globus_xio_driver_transform_open_t) (const
       globus_xio_contact_t *contact_info, void *driver_link, void
       *driver_attr, globus_xio_operation_t op)

open a handle. this is called when a user opens a handle. so like, opening time. 🚪

Parameters:

contact_info — contains information about the requested resource. Its members may all be null (especially when link is not null). XIO will destroy this contact info upon return from the interface function.
driver_link — comes from server accept. Used to link an accepted connection to an xio handle. XIO will destroy this object upon the return of this interface call.
driver_attr — a attribute describing how to open. This points to a piece of memory created by the globus_xio_driver_attr_init_t interface function.
op — the open operation. When the driver is finished opening the handle, it passes this to globus_xio_driver_finished_open() to return status up the driver stack to the application.

`globus_xio_driver_transport_open_t`

   typedef globus_result_t(* globus_xio_driver_transport_open_t) (const
       globus_xio_contact_t *contact_info, void *driver_link, void
       *driver_attr, globus_xio_operation_t op)

open a handle. this is called when a user opens a handle. (same vibe as the transform one, but for transport drivers.) 🚀

Parameters:

contact_info — contains information about the requested resource. Its members may all be null (especially when link is not null). XIO will destroy this contact info upon return from the interface function.
driver_link — comes from server accept. Used to link an accepted connection to an xio handle. XIO will destroy this object upon the return of this interface call.
driver_attr — a attribute describing how to open. This points to a piece of memory created by the globus_xio_driver_attr_init_t interface function.
op — the open operation. When the driver is finished opening the handle, it passes this to globus_xio_driver_finished_open() to return status up the driver stack to the application.

`globus_xio_driver_write_t`

   typedef globus_result_t(* globus_xio_driver_write_t) (void
       *driver_specific_handle, const globus_xio_iovec_t *iovec, int
       iovec_count, globus_xio_operation_t op)

write data from an open handle. wait, it says "from an open handle" but it's write, so it's to an open handle? but we keep it exact: "write data from an open handle." this function is called when the user requests to write data to a handle. the driver author shall implement all code needed to for there driver to complete write operations. (again, "for there driver" — keeping it.) ✍️

Parameters:

driver_specific_handle — the driver handle to which data should be written.
iovec — an io vector pointing to the buffers to be written.
iovec_count — the number if entries in the io vector.
op — the requested operation. When the driver is finished fulfilling the requested read operation it must use this structure to signal globus_xio that the operation is completed. This is done by calling globus_xio_driver_finished_operation(). (yes, it says "read operation" in the write one. we keep it exact.)

🌟 Function Documentation 🌟

`globus_bool_t globus_xio_driver_eof_received (globus_xio_operation_t op)`

   globus_bool_t globus_xio_driver_eof_received (globus_xio_operation_t op)

EOF state checking. this function is used by drivers that allow multiple outstanding reads at a time. it can only be called on behalf of a read operation (while in the read interface call or the pass_read callback). so like, only when you're in the read zone. 📖

Typical use of this? Bestie, you grab your driver-specific lock — the same one you use when you call globus_xio_driver_set_eof_received() — and you call this to check if an EOF has landed. If it has, finish the operation immediately with an EOF error. Do not return an EOF error. 💀

This call is typically only used inside the read interface call.

Parameters

op — the operation structure that represents the requested read operation.

Returns

GLOBUS_TRUE if an EOF was received, GLOBUS_FALSE otherwise.

✨ `globus_xio_driver_finished_accept`

void globus_xio_driver_finished_accept (globus_xio_operation_t op, void *
    driver_link, globus_result_t result)

Driver API finished accept 🎀

Call this to tell globus_xio that the accept operation it asked you for is done. It frees up the resources tied to the accept_op, and it may make xio pop that signal right up the driver stack.

Parameters

op — the requested accept operation that has completed.
driver_link — the initialized driver link that will be passed to the open interface when this handle is opened.
result — return status of the completed operation.

✨ `globus_xio_driver_finished_close`

void globus_xio_driver_finished_close (globus_xio_operation_t op,
    globus_result_t result)

Driver API finished_close 🫶

You call this after you've finished a close operation on a driver_handle. Heads up though: the moment this function returns, that driver_handle is no longer valid. Poof. Gone. 🦋

Parameters

op — the close operation that has completed.
result — return status of the completed operation.

✨ `globus_xio_driver_finished_open`

void globus_xio_driver_finished_open (void * driver_handle,
    globus_xio_operation_t op, globus_result_t result)

Driver API finished open ✨

Call this to signal globus_xio that the open operation it requested is complete. It frees the resources associated with op, and it may make xio pop the signal up the driver stack.

Parameters

driver_handle — the driver specific handle pointer that will be passed to future interface function calls.
op — the requested open operation that has completed.
result — return status of the completed operation.

✨ `globus_xio_driver_finished_read`

void globus_xio_driver_finished_read (globus_xio_operation_t op,
    globus_result_t result, globus_size_t nread)

Finished Read 🌸

Call this to signal globus_xio that the requested read operation is done.

Parameters

op — the operation structure representing the requested read operation.
result — return status of the completed operation.
nread — the number of bytes read.

✨ `globus_xio_driver_finished_write`

void globus_xio_driver_finished_write (globus_xio_operation_t op,
    globus_result_t result, globus_size_t nwritten)

Finished Write 🌸

Call this to signal globus_xio that the requested write operation is done.

Parameters

op — the operation structure representing the requested write operation.
result — return status of the completed operation.
nwritten — the number of bytes written.

✨ `globus_xio_driver_handle_cntl`

globus_result_t globus_xio_driver_handle_cntl (globus_xio_driver_handle_t
    handle, globus_xio_driver_t driver, int cmd,  ...)

Touch driver specific information in a handle object. 👑

okay so here's the deal, bestie:

pass the driver to control a specific driver
pass NULL for driver for XIO specific cntls
pass GLOBUS_XIO_QUERY for driver if you want it to try each driver (below the current one) in order

✨ `globus_xio_driver_merge_operation`

globus_result_t globus_xio_driver_merge_operation (globus_xio_operation_t
    top_op, globus_xio_operation_t bottom_op)

Finishes an operation and merge two op structures. (XXX not implemented yet) 💀

Not gonna lie, the XXX not implemented yet is doing a lot of heavy lifting in that title. 🙈

This function joins two operations together and signals globus_xio that it's completed. It's an advanced function — most drivers will not require its use, fr fr.

What it does: it takes an operation that this driver created and passed down to drivers lower on the stack, plus an operation that came in on the interface function (the one that saw the top half of the stack), and joins them together. The whole point is to join data descriptors that were pre-staged and cached with the ones that came in later at the user's request. See the read ahead doc for more info. 📚

Parameters

top_op — the operation that has seen the top part of the driver stack.
bottom_op — the operation that has seen the bottom part of the driver stack.

(result is always success in this case. if there is an error, use the other finish() call)

✨ `globus_xio_driver_operation_create`

globus_result_t globus_xio_driver_operation_create (globus_xio_operation_t *
    operation, globus_xio_driver_handle_t handle)

Driver API Create Operation 🎀

This creates an operation out of an initialized handle. Then you can use that operation for io operations related to the handle that created it. It's giving ✨main character energy✨ for your io.

Parameters

operation — the operation to be created. When this function returns, this structure will be populated and available for the driver to use.
handle — the initialized handle representing the user handle from which the operation will be created.

✨ `globus_xio_driver_operation_is_blocking`

globus_bool_t globus_xio_driver_operation_is_blocking
    (globus_xio_operation_t operation)

Is Operation blocking. 🧚

If the operation is blocking, the driver developer may be able to make certain optimizations. The function returns true if the given operation was created via a user call to a blocking function.

✨ `globus_xio_driver_pass_close`

globus_result_t globus_xio_driver_pass_close (globus_xio_operation_t op,
    globus_xio_driver_callback_t cb, void * callback_arg)

Pass the close operation down the driver stack. 💅

This passes a close request down the driver stack. When the close operation completes, globus_xio will call the function pointed to by the cb parameter.

Parameters

op — the close operation.
cb — a pointer to the function to be called once all drivers lower in the stack have closed.
callback_arg — a pointer that will be passed to the callback.

✨ `globus_xio_driver_pass_open`

globus_result_t globus_xio_driver_pass_open (globus_xio_operation_t op,
    const globus_xio_contact_t * contact_info, globus_xio_driver_callback_t
    cb, void * user_arg)

Driver API Open 🌈

This passes an open request down the driver stack. When the open operation completes, globus_xio calls the cb function — at that point the handle structure is initialized and available for use.

And the moment this function returns, the handle is valid for creating other operations. No waiting, periodt. ⭐

Parameters

op — the operation from which the handle will be established. This parameter is used to determine what drivers are in the stack and other such information.
contact_info — the contact info describing the resource the driver below should open. This will normally be the same contact info that was passed in on the open interface.
cb — the function to be called when the open operation is complete.
user_arg — a user pointer that will be threaded through to the callback.

✨ `globus_xio_driver_pass_read`

globus_result_t globus_xio_driver_pass_read (globus_xio_operation_t op,
    globus_xio_iovec_t * iovec, int iovec_count, globus_size_t wait_for,
    globus_xio_driver_data_callback_t cb, void * user_arg)

Driver read 💖

This passes a read operation down the driver stack. After this function is called, the op structure is no longer valid. But when the driver stack finishes servicing the read request, it will pass a new operation structure in the function pointed to by cb. Then you can call finish read on that new operation you received. 🔥

Parameters

op — the operation structure representing this requested io operation.
iovec — a pointer to the array of iovecs.
iovec_count — the number of iovecs in the array.
wait_for — the minimum number of bytes to read before returning. If a driver has no specific requirement, he should use the user's request available via GlobusXIOOperationMinimumRead(op).
cb — the function to be called when the operation request is completed.
user_arg — a user pointer that will be threaded through to the callback.

✨ `globus_xio_driver_pass_write`

globus_result_t globus_xio_driver_pass_write (globus_xio_operation_t op,
    globus_xio_iovec_t * iovec, int iovec_count, globus_size_t wait_for,
    globus_xio_driver_data_callback_t cb, void * user_arg)

Driver write 💖

This passes a write operation down the driver stack. Same deal as read: after this function is called, the op structure is no longer valid. But when the driver stack finishes servicing the write request, it will pass a new operation structure in the function pointed to by cb. Finished write can be called on the new operation received. ✨

Parameters

op — the operation structure representing this requested io operation.
iovec — a pointer to the array of iovecs.
iovec_count — the number of iovecs in the array.
wait_for — the minimum number of bytes to write before returning. If a driver has no specific requirement, he should use the user's request available via GlobusXIOOperationMinimumWrite(op).
cb — the function to be called when the operation request is completed.
user_arg — a user pointer that will be threaded through to the callback.

✨ `globus_xio_driver_set_eof_received`

void globus_xio_driver_set_eof_received (globus_xio_operation_t op)

EOF state manipulation 🌸

This one's for drivers that allow multiple outstanding reads at a time. It can only be called on behalf of a read operation — meaning while you're in the read interface call, or in the pass_read callback.

Typical use: hold a driver specific lock, then call this when an internal EOF has been received. The read operation you're calling this on behalf of must be finished with an EOF error, or the results are undefined. 🫠 (respect the undefined behaviour bestie, she's dramatic)

In general, you should not have an EOF flag in your driver. Use this call and globus_xio_driver_eof_received() instead. Why? Because it's necessary to support XIO's automatic EOF resetting. The only exception: if your driver absolutely cannot be read after an EOF has been set, then you'll need your own EOF flag. 🙈

This call will typically only be used just before a finished_read() call.

Parameters

op — the operation structure representing the requested read operation.

✨ `globus_xio_driver_set_server_pre_init`

globus_result_t globus_xio_driver_set_server_pre_init (globus_xio_driver_t
    driver, globus_xio_driver_server_init_t server_pre_init_func)

Server Pre-Init. 👑

This function adds a callback to a driver that will be called before a server handle is created by XIO. It has the same signature as the server_init_func in the driver, but it's always called with a NULL contact string.

There is no support for calling a pass() or finished() function for this interface. 😭 It may inspect and modify its attributes and operation, but it can't directly return any data or set a driver-specific server handle value.

If this function returns an error result, the server create will be aborted. 💀

✨ Parameters 🎀

driver — the driver you're attaching this function to, bestie 💖
server_pre_init_func — the function that gets called before a server gets created 🌸

✨ Return values 💜

GLOBUS_SUCCESS — it worked, we ate, no crumbs 🍓✨
GLOBUS_XIO_ERROR_PARAMETER — uh oh, a parameter was invalid 🙈 the vibe check failed

👑 AUTHOR ✨

Generated automatically by Doxygen for globus_xio from the source code. Not me handwriting it in my notes app at 2am, the bots did that 💅🤖

And that's a wrap on globus_xio_driver(3) bestie!! 🎀🦋 You just made it through the whole entire thing and honestly? Iconic behavior, main character energy fr fr. Go forth and write drivers, you absolute legend 👑💖

globus_xio — Version 6.6 — globus_xio_driver(3) ✨ that's the source, that's the version, that's the manual page, periodt 💅

📦 where this page comes from

fedora 44: globus-xio-doc 6.6-10.fc44 · Apache-2.0
ubuntu resolute: libglobus-xio-doc 6.6-3build2 · Apache-2.0
ubuntu stonking: libglobus-xio-doc 6.6-4 · Apache-2.0
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-03: a language model's rewrite of the original, under its terms

globus_xio_driver(3)

✨ NAME ✨

🦋 SYNOPSIS 🦋

🌸 Topics 🌸

💅 Driver Programming: String options 💅

🎀 Typedefs 🎀

🌈 Functions 🌈

💖 Detailed Description 💖

🚀 Driver Types 🚀

👑 Driver API 👑

🌟 Quick Start 🌟

🦄 Typical Sequence: 🦄

🧚 Globus XIO Attributes 🧚

✨ Advanced Driver Programming ✨

🦋 Read Ahead 🦋

✨ Typedef Documentation ✨

globus_xio_driver_attr_cntl_t

globus_xio_driver_attr_copy_t

globus_xio_driver_attr_destroy_t

globus_xio_driver_attr_init_t

globus_xio_driver_callback_t

globus_xio_driver_close_t

globus_xio_driver_data_callback_t

globus_xio_driver_handle_cntl_t

globus_xio_driver_link_destroy_t

globus_xio_driver_read_t

globus_xio_driver_server_accept_t

globus_xio_driver_server_cntl_t

globus_xio_driver_server_destroy_t

globus_xio_driver_server_init_t

globus_xio_driver_transform_open_t

globus_xio_driver_transport_open_t

globus_xio_driver_write_t

🌟 Function Documentation 🌟

globus_bool_t globus_xio_driver_eof_received (globus_xio_operation_t op)

✨ globus_xio_driver_finished_accept

✨ globus_xio_driver_finished_close

✨ globus_xio_driver_finished_open

✨ globus_xio_driver_finished_read

✨ globus_xio_driver_finished_write

✨ globus_xio_driver_handle_cntl

✨ globus_xio_driver_merge_operation

✨ globus_xio_driver_operation_create

✨ globus_xio_driver_operation_is_blocking

✨ globus_xio_driver_pass_close

✨ globus_xio_driver_pass_open

✨ globus_xio_driver_pass_read

✨ globus_xio_driver_pass_write

✨ globus_xio_driver_set_eof_received

✨ globus_xio_driver_set_server_pre_init

✨ Parameters 🎀

✨ Return values 💜

👑 AUTHOR ✨

`globus_xio_driver_attr_cntl_t`

`globus_xio_driver_attr_copy_t`

`globus_xio_driver_attr_destroy_t`

`globus_xio_driver_attr_init_t`

`globus_xio_driver_callback_t`

`globus_xio_driver_close_t`

`globus_xio_driver_data_callback_t`

`globus_xio_driver_handle_cntl_t`

`globus_xio_driver_link_destroy_t`

`globus_xio_driver_read_t`

`globus_xio_driver_server_accept_t`

`globus_xio_driver_server_cntl_t`

`globus_xio_driver_server_destroy_t`

`globus_xio_driver_server_init_t`

`globus_xio_driver_transform_open_t`

`globus_xio_driver_transport_open_t`

`globus_xio_driver_write_t`

`globus_bool_t globus_xio_driver_eof_received (globus_xio_operation_t op)`

✨ `globus_xio_driver_finished_accept`

✨ `globus_xio_driver_finished_close`

✨ `globus_xio_driver_finished_open`

✨ `globus_xio_driver_finished_read`

✨ `globus_xio_driver_finished_write`

✨ `globus_xio_driver_handle_cntl`

✨ `globus_xio_driver_merge_operation`

✨ `globus_xio_driver_operation_create`

✨ `globus_xio_driver_operation_is_blocking`

✨ `globus_xio_driver_pass_close`

✨ `globus_xio_driver_pass_open`

✨ `globus_xio_driver_pass_read`

✨ `globus_xio_driver_pass_write`

✨ `globus_xio_driver_set_eof_received`

✨ `globus_xio_driver_set_server_pre_init`