---
name: "driver_pgm"
section: "3"
platform: "linux"
package: "libglobus-xio-doc"
version: "3.3-1"
release: "Debian 7 (Wheezy)"
platforms: ["linux"]
url: "https://new.carta.tech/driver_pgm"
---

# driver\_pgm(3)

## NAME

Driver Programming -

### Typedefs

typedef void(\* **globus\_xio\_driver\_callback\_t** )(globus\_xio\_operation\_t op, globus\_result\_t result, void \*user\_arg)\
 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 \*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)\
 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)\
 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\_handle, void \*driver\_attr, globus\_xio\_operation\_t op)\
 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\_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 \*user\_arg)\
 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

The set of interface functions that the driver author must implement to create a driver and the functions to assist in the creation.

Driver attribute functions

If the driver wishes to provide driver specific attributes to the user it must implement the following functions:

globus\_xio\_driver\_attr\_init\_t globus\_xio\_driver\_attr\_copy\_t globus\_xio\_driver\_attr\_cntl\_t globus\_xio\_driver\_attr\_destroy\_t

## Typedef Documentation

### typedef void(\* globus\_xio\_driver\_callback\_t)(globus\_xio\_operation\_t op, globus\_result\_t result, void \*user\_arg)

callback interface

This is the function signature of callbacks for the globus\_xio\_driver\_open/close(). **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 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 approriate 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\_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 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\_cntl\_t)(void \*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 resonsible 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\_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 (pasive opens). In the tcp driver this function should create a listener.

**Parameters:**

*op* An op which should be passed to globus\_xio\_driver\_server\_created. Note, that unlike most operations, the server is created from the bottom of the stack to the top.\
 *contact\_info* This the contact info for the stack below this driver. (entries will always be NULL for the transport driver)\
 *driver\_attr* A server attr if the user specified any driver specific attributes. This may be NULL.

**Returns:**

Returning GLOBUS\_SUCCESS for this means that \` globus\_xio\_driver\_pass\_server\_init returned success and the driver's server was successfully initialized.

### 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:**

*server* The server that the driver should clean up.\
 *driver\_server* The reference to the iunternal server that is being declaired invaild with this function call.

### 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 opertunity 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 acepting 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\_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\_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 requests to open a handle. **Parameters:**

*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\_driver\_attr\_init\_t interface funstion.\
 *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\
 *op* The requested operation. When the driver is finished opening the handle it uses this structure to signal globus\_xio that it has completed the operation requested. It does this by calling **globus\_xio\_driver\_finished\_open()**

### 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)

transport open

### 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\_close\_t)(void \*driver\_handle, void \*driver\_attr, globus\_xio\_operation\_t op)

Close an open handle

This is called when a user requests to close a handle. The driver implemntor should clean up all resources connected to there driver handle when this function is called.

**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 requested operation. When the driver is finished closing the handle it uses this structure to signal globus\_xio that it has completed the operation requested. It does this by calling **globus\_xio\_driver\_finished\_close()**

### 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\_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 fullfilling 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\_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\_handle* The driver handle to which data should be writen.\
 *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 fullfilling 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\_result\_t globus\_xio\_driver\_handle\_cntl (globus\_xio\_driver\_handle\_thandle, globus\_xio\_driver\_tdriver, intcmd, ...)

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

References globus\_xio\_driver\_handle\_cntl().

### void globus\_xio\_driver\_finished\_accept (globus\_xio\_operation\_top, void \*driver\_link, globus\_result\_tresult)

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 potientially 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

References globus\_xio\_driver\_finished\_accept().

### globus\_result\_t globus\_xio\_driver\_pass\_open (globus\_xio\_operation\_top, const globus\_xio\_contact\_t \*contact\_info, globus\_xio\_driver\_callback\_tcb, 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 intialized 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 wehn the open operation is complete.\
 *user\_arg* a user pointer that will be threaded through to the callback.

References globus\_xio\_driver\_pass\_open().

### void globus\_xio\_driver\_finished\_open (void \*driver\_handle, globus\_xio\_operation\_top, globus\_result\_tresult)

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 potientially 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 funstion calls.\
 *op* The requested open operation that has completed.\
 *result* Return status of the completed operation

References globus\_xio\_driver\_finished\_open().

### globus\_result\_t globus\_xio\_driver\_operation\_create (globus\_xio\_operation\_t \*operation, globus\_xio\_driver\_handle\_thandle)

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.

References globus\_xio\_driver\_operation\_create().

### globus\_bool\_t globus\_xio\_driver\_operation\_is\_blocking (globus\_xio\_operation\_toperation)

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

### globus\_result\_t globus\_xio\_driver\_pass\_close (globus\_xio\_operation\_top, globus\_xio\_driver\_callback\_tcb, void \*user\_arg)

Driver API Close

This function will pass a close request down the driver stack. Upon completion of the close operation globus\_xio will call the funciton pointed to by the cb argument.

**Parameters:**

*op* The operation to pass along the driver stack for closing.\
 *cb* A pointer to the function to be called once all drivers lower in the stack have closed.\
 *user\_arg* A user pointer that will be threaded through to the callback.

References globus\_xio\_driver\_pass\_close().

### void globus\_xio\_driver\_finished\_close (globus\_xio\_operation\_top, globus\_result\_tresult)

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

References globus\_xio\_driver\_finished\_close().

### globus\_result\_t globus\_xio\_driver\_pass\_read (globus\_xio\_operation\_top, globus\_xio\_iovec\_t \*iovec, intiovec\_count, globus\_size\_twait\_for, globus\_xio\_driver\_data\_callback\_tcb, 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 funciton pointed to by cb. Finishe 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 specifc 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.

References globus\_xio\_driver\_pass\_read().

### void globus\_xio\_driver\_finished\_read (globus\_xio\_operation\_top, globus\_result\_tresult, globus\_size\_tnread)

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

References globus\_xio\_driver\_finished\_read().

### void globus\_xio\_driver\_set\_eof\_received (globus\_xio\_operation\_top)

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.

References globus\_xio\_driver\_set\_eof\_received().

### globus\_bool\_t globus\_xio\_driver\_eof\_received (globus\_xio\_operation\_top)

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.

References globus\_xio\_driver\_eof\_received().

### globus\_result\_t globus\_xio\_driver\_pass\_write (globus\_xio\_operation\_top, globus\_xio\_iovec\_t \*iovec, intiovec\_count, globus\_size\_twait\_for, globus\_xio\_driver\_data\_callback\_tcb, 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 funciton 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 specifc 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.

References globus\_xio\_driver\_pass\_write().

### void globus\_xio\_driver\_finished\_write (globus\_xio\_operation\_top, globus\_result\_tresult, globus\_size\_tnwritten)

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

References globus\_xio\_driver\_finished\_write().

### globus\_result\_t globus\_xio\_driver\_merge\_operation (globus\_xio\_operation\_ttop\_op, globus\_xio\_operation\_tbottom\_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 prestaged 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)

## Author

Generated automatically by Doxygen for globus xio from the source code.