--- name: "globus_xio_driver" section: "3" platform: "linux" package: "libglobus-xio-doc" version: "6.6-3" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/globus_xio_driver" --- # globus\_xio\_driver(3) Globus XIO Driver - Globus XIO Driver. ## NAME globus\_xio\_driver - Globus XIO Driver \- Globus XIO Driver. ## SYNOPSIS ### Modules **Driver Programming: String options**\ Driver Programming: String options. ### Typedefs typedef void(\* **globus\_xio\_driver\_callback\_t**) (globus\_xio\_operation\_t op, globus\_result\_t result, void \*user\_arg)\ Open and Close Callback Signature. typedef void(\* **globus\_xio\_driver\_data\_callback\_t**) (globus\_xio\_operation\_t op, globus\_result\_t result, globus\_size\_t nbytes, void \*user\_arg)\ typedef globus\_result\_t(\* **globus\_xio\_driver\_attr\_init\_t**) (void \*\*out\_driver\_attr)\ typedef globus\_result\_t(\* **globus\_xio\_driver\_attr\_copy\_t**) (void \*\*dst, void \*src)\ typedef globus\_result\_t(\* **globus\_xio\_driver\_attr\_destroy\_t**) (void \*driver\_attr)\ typedef globus\_result\_t(\* **globus\_xio\_driver\_attr\_cntl\_t**) (void \*driver\_attr, int cmd, va\_list ap)\ 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)\ typedef globus\_result\_t(\* **globus\_xio\_driver\_server\_destroy\_t**) (void \*driver\_server)\ typedef globus\_result\_t(\* **globus\_xio\_driver\_server\_accept\_t**) (void \*driver\_server, globus\_xio\_operation\_t op)\ typedef globus\_result\_t(\* **globus\_xio\_driver\_server\_cntl\_t**) (void \*driver\_server, int cmd, va\_list ap)\ typedef globus\_result\_t(\* **globus\_xio\_driver\_link\_destroy\_t**) (void \*driver\_link)\ 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. 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. typedef globus\_result\_t(\* **globus\_xio\_driver\_handle\_cntl\_t**) (void \*handle, int cmd, va\_list ap)\ typedef globus\_result\_t(\* **globus\_xio\_driver\_close\_t**) (void \*driver\_specific\_handle, void \*driver\_attr, globus\_xio\_operation\_t op)\ Close a handle. 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)\ 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\_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. globus\_result\_t **globus\_xio\_driver\_handle\_cntl** (globus\_xio\_driver\_handle\_t handle, globus\_xio\_driver\_t driver, int cmd,...)\ void **globus\_xio\_driver\_finished\_accept** (globus\_xio\_operation\_t op, void \*driver\_link, globus\_result\_t result)\ 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)\ void **globus\_xio\_driver\_finished\_open** (void \*driver\_handle, globus\_xio\_operation\_t op, globus\_result\_t result)\ globus\_result\_t **globus\_xio\_driver\_operation\_create** (globus\_xio\_operation\_t \*operation, globus\_xio\_driver\_handle\_t handle)\ globus\_bool\_t **globus\_xio\_driver\_operation\_is\_blocking** (globus\_xio\_operation\_t operation)\ 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. void **globus\_xio\_driver\_finished\_close** (globus\_xio\_operation\_t op, globus\_result\_t result)\ 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)\ void **globus\_xio\_driver\_finished\_read** (globus\_xio\_operation\_t op, globus\_result\_t result, globus\_size\_t nread)\ void **globus\_xio\_driver\_set\_eof\_received** (globus\_xio\_operation\_t op)\ globus\_bool\_t **globus\_xio\_driver\_eof\_received** (globus\_xio\_operation\_t op)\ 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)\ void **globus\_xio\_driver\_finished\_write** (globus\_xio\_operation\_t op, globus\_result\_t result, globus\_size\_t nwritten)\ 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 introduces a notion of a driver stack to its API. Within globus\_xio every I/O operation must occur on a globus\_xio handle. Associated with each handle is a stack of drivers. A driver is a modulular piece of code that implements the globus\_xio driver interface. The purpose of a driver is manipulate data passed in by the user in someway. Each driver in a stack will serve its own unique purpose. I/O operations pass from driver to driver, starting at the top of the stack and ending at the bottom. When the bottom layer driver finishes with the operation it signals globus\_xio that it has completed. \ \ Completion notification then flows up to the top of the driver stack. ## Driver Types - **Transport driver:** A transport driver is one that 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, at its 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 of a transform driver would one which implements a network protocol such as http. This driver would frame and parse messages, but 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 to allow a developer to 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 the 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 The typical driver implementation is describe above. However globus\_xio allows driver authors to do more advanced things such as initiating operations on their own. - **Read Ahead** Once a handle is open, a driver can create operation structures from it. A driver can then request I/O from the driver stack before it receives a call to its own I/O interface functions, implementing read-ahead functionality. This can be done as follows: - 1\. Obtain a driver handle from the open operation by calling globus\_xio\_operation\_get\_driver\_handle() - 2\. Create an operation by calling **globus\_xio\_driver\_operation\_create()** and pass it the driver\_handle from the previous step - 3\. call **globus\_xio\_driver\_pass\_read()** using this operation. When the read callback is received, the driver saves the returned data in its private data and then calls **globus\_xio\_driver\_finished\_read()** on the operation. - 4\. When XIO calls the driver's read interface function, the driver can immediately call **globus\_xio\_driver\_finished\_read()** function after updating the iovec structure with the data it had previously read. ## Typedef Documentation ### typedef globus\_result\_t(\* globus\_xio\_driver\_attr\_cntl\_t) (void \*driver\_attr, int cmd, va\_list ap) get or set information in an attr. The cmd parameter determines what functionality the user is requesting. The driver is responsible for providing documentation to the user on all the possible values that cmd can be. **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. ### typedef globus\_result\_t(\* globus\_xio\_driver\_attr\_copy\_t) (void \*\*dst, void \*src) Copy a driver attr. When this function is called the driver will create a copy of the attr in parameter src and place it in the parameter dst. ### typedef globus\_result\_t(\* globus\_xio\_driver\_attr\_destroy\_t) (void \*driver\_attr) Destroy the driver attr. Clean up all resources associate with the attr. ### 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. ### 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. **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. ### 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(). In the close callback, the driver should clean up the data associated with driver\_handle. **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. ### 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. \ **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. ### typedef globus\_result\_t(\* globus\_xio\_driver\_handle\_cntl\_t) (void \*handle, int cmd, va\_list ap) this call *must* return an GLOBUS\_XIO\_ERROR\_COMMAND error for unsupported command numbers. (use GlobusXIOErrorInvalidCommand(cmd)) 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. ### 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. **Parameters** *driver\_link* The link to be destroyed. ### 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. **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.\ *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(). ### 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. **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. ### 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. **Parameters** *driver\_server* the server handle.\ *cmd* An integer telling the driver what operation to preform on this server handle.\ *ap* variable args. ### 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. **Parameters** *driver\_server* The reference to the internal server that is being declared invalid with this function call. ### 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. **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. ### 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. **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. ### 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. **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. ### 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. 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. **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(). ## Function Documentation ### 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). Typical use for this would be to hold a driver specific lock (the same one used when calling **globus\_xio\_driver\_set\_eof\_received()**) and call this to see if an EOF has been received. If so, the operation should immediately be finished with an EOF error (do not *return* an EOF error). This call will typically only be used in the read interface call. **Parameters** *op* The operation structure representing the requested read operation. **Returns** GLOBUS\_TRUE if EOF received, GLOBUS\_FALSE otherwise. ### void globus\_xio\_driver\_finished\_accept (globus\_xio\_operation\_t op, void \* driver\_link, globus\_result\_t result) Driver API finished accept This function should be called to signal globus\_xio that it has completed the accept operation requested of it. It will free up resources associated with the accept\_op and potentially cause xio to pop the signal up the driver stack. **Parameters** *op* The requested accept operation that has completed.\ *driver\_link* This is the initialized driver link that is that will be passed to the open interface when this handle is opened.\ *result* Return status of the completed operation ### void globus\_xio\_driver\_finished\_close (globus\_xio\_operation\_t op, globus\_result\_t result) Driver API finished\_close The driver calls this function after completing a close operation on a driver\_handle. Once this function returns the driver\_handle is no longer valid. **Parameters** *op* The close operation that has completed.\ *result* Return status of the completed operation ### void globus\_xio\_driver\_finished\_open (void \* driver\_handle, globus\_xio\_operation\_t op, globus\_result\_t result) Driver API finished open This function should be called to signal globus\_xio that it has completed the open operation requested of it. It will free up resources associated with the op and potentially cause xio to 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 ### void globus\_xio\_driver\_finished\_read (globus\_xio\_operation\_t op, globus\_result\_t result, globus\_size\_t nread) Finished Read This function is called to signal globus\_xio that the requested read operation has been completed. **Parameters** *op* The operation structure representing the requested read operation.\ *result* Return status of the completed operation\ *nread* The number of bytes read ### void globus\_xio\_driver\_finished\_write (globus\_xio\_operation\_t op, globus\_result\_t result, globus\_size\_t nwritten) Finished Write This function is called to signal globus\_xio that the requested write operation has been completed. **Parameters** *op* The operation structure representing the requested write operation.\ *result* Return status of the completed operation\ *nwritten* The number of bytes written ### 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. 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 (below current) in order ### 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) This function will join to operations together and signal globus\_xio that it has completed. This is an advanced function. Most drivers will not require its use. This function takes an operation that was created by this driver and passed on to drivers lower on the stack and an operation that came in on the interface function (that has seen the top half of the stack) and joins them together. The purpose of this function is to join data descriptors that were pre-staged and cached with those that have later come in at the users request. See the read ahead doc for more information. **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\_result\_t globus\_xio\_driver\_operation\_create (globus\_xio\_operation\_t \* operation, globus\_xio\_driver\_handle\_t handle) Driver API Create Operation This function will create an operation from an initialized handle This operation can then be used for io operations related to the handle that created them. **Parameters** *operation* The operation to be created. When this function returns this structure will be populated and available for use for the driver.\ *handle* The initialized handle representing the user handle from which the operation will be created. ### 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\_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 function will pass a close request down the driver stack. Upon completion of the close operation 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\_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 function will pass an open request down the driver stack. Upon completion of the open operation globus\_xio will call the *cb* function, at which point the handle structure will be initialized and available for use. As soon as the function returns the handle is valid for creating other operations. **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\_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 function passes a read operation down the driver stack. After this function is called the op structure is no longer valid. However when the driver stack finishes servicing the read request it will pass a new operation structure in the function pointed to by cb. Finish read 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 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\_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 function passes a write operation down the driver stack. After this function is called the op structure is no longer valid. However 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. ### void globus\_xio\_driver\_set\_eof\_received (globus\_xio\_operation\_t op) EOF state manipulation 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). Typical use for this would be to hold a driver specific lock and call this when an internal EOF has been received. The read operation this is called on behalf of must be finished with an EOF error or the results are undefined. In general, you should not have an EOF flag in your driver. Use this call and **globus\_xio\_driver\_eof\_received()** instead. This is necessary to support XIO's automatic EOF resetting. If your driver absolutely can not be read after an EOF has been set, then you will 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\_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. This function has the same signature as the server\_init\_func in the driver, but is 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 can not 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* Driver to associate the function with \ *server\_pre\_init\_func* Function to call prior to creating a server **Return values** *GLOBUS\_SUCCESS* Success \ *GLOBUS\_XIO\_ERROR\_PARAMETER* Invalid parameter ## Author Generated automatically by Doxygen for globus\_xio from the source code.