---
name: "GLOBUS_XIO_API_ASSIST"
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_API_ASSIST"
---

# GLOBUS\_XIO\_API\_ASSIST(3)

XIO Examples - XIO Examples.

## NAME

GLOBUS\_XIO\_API\_ASSIST - XIO Examples

 \- XIO Examples.

## SYNOPSIS

## Detailed Description

XIO Examples.

Help understanding the globus\_xio api.

## Stack Construction

The driver stack that is used for a given XIO handle is constructed using a globus\_xio\_stack\_t. Each driver is loaded by name and pushed onto a stack.

Stack setup example:

```
// First load the drivers
globus_xio_driver_load("tcp", &tcp_driver);
globus_xio_driver_load("gsi", &gsi_driver);
//build the stack
globus_xio_stack_init(&stack);
globus_xio_stack_push_driver(stack, tcp_driver, NULL);
globus_xio_stack_push_driver(stack, gsi_driver, NULL);
```

## Servers

A server data structure provides functionality for passive opens. A server is initialized and bound to a protocol stack and set of attributes with the function **globus\_xio\_server\_create()**. Once a server is created many 'connections' can be accepted. Each connection will result in an initialized handle which can later be opened.

```
globus_xio_server_t             server;
globus_xio_attr_t               attr;
globus_xio_attr_init(&attr);
globus_xio_server_create(&server_handle, attr, stack);
globus_xio_server_accept(&handle, server);
```

## Handle Construction

There are two ways to create a handle. The first is for use as a client (one that is doing an active open). The function: **globus\_xio\_handle\_create()** is used to create such a handle and bind that handle to a protocol stack.

```
globus_xio_handle_create(&handle, stack);
```

The second means of creating a handle is for use as a server (one that is doing a passive open). This is created by accepting a connection on a server\_handle with the function **globus\_xio\_server\_accept()** or **globus\_xio\_server\_register\_accept()**.

Mutable attrs can be altered via a call to **globus\_xio\_handle\_cntl()** described later.

```
globus_xio_server_accept(&xio_handle, server_handle);
```

once a handle is initialized the user can call **globus\_xio\_open()** to begin the open process.

## Timeouts

A user can set a timeout value for any I/O operation. Each I/O operation (open close read write) can have its own timeout value. If no timeout is set the operation will be allowed to infinitely block.

When time expires the outstanding operation is canceled. If the timeout callback for the given operation is not NULL it is called first to notify the user that the operation timed out and give the user a chance to ignore that timeout. If canceled, the user will get the callback they registered for the operation as well, but it will come with an error indicating that it has been canceled.

It is possible that part of an I/O operation will complete before the timeout expires. In this case the operation can still be canceled. The user will receive there IO callback with and error set and the length value appropriately set to indicate how much of the operation completed.

Timeouts are registered by using the following handle\_cntl values:

- •

  GLOBUS\_XIO\_ATTR\_SET\_TIMEOUT\_ALL

- •

  GLOBUS\_XIO\_ATTR\_SET\_TIMEOUT\_OPEN

- •

  GLOBUS\_XIO\_ATTR\_SET\_TIMEOUT\_CLOSE

- •

  GLOBUS\_XIO\_ATTR\_SET\_TIMEOUT\_READ

- •

  GLOBUS\_XIO\_ATTR\_SET\_TIMEOUT\_WRITE

- •

  GLOBUS\_XIO\_ATTR\_SET\_TIMEOUT\_ACCEPT

Each of these cntls expect three parameters:

- •

  globus\_xio\_timeout\_callback\_t callback\_function

- •

  globus\_reltime\_t \* delay\_time

- •

  void \* callback\_arg

## Data Descriptor

The data descriptor ADT gives the user a means of attaching/extracting meta data to a read or write operation.\
\
  Things like offset, out of band message, and other driver specific meta data are contained in the data descriptor.\
\
  Data descriptors are passed to globus\_xio in **globus\_xio\_read()** and **globus\_xio\_write()**. Within the globus\_xio framework it is acceptable to pass NULL instead of a valid data\_descriptor,

Example:

```
globus_xio_data_descriptor_init(&desc);
globus_xio_data_descriptor_cntl(desc,
    tcp_driver,
    GLOBUS_XIO_TCP_SET_SEND_FLAGS,
    GLOBUS_XIO_TCP_SEND_OOB);
```

## User Attributes

Globus XIO uses a single attribute object for all of its functions. Attributes give the user an extensible mechanism to alter default values which control parameters in an operation.

In most of the Globus XIO user API functions a user passes an attribute as a parameter. In many cases the user may ignore the attribute parameter and just pass in NULL. However at times the user will wish to tweak the operation. The attribute structure is used for this tweaking.

There are only three attribute functions. **globus\_xio\_attr\_init** **globus\_xio\_attr\_cntl** and **globus\_xio\_attr\_destroy**. The init and destroy functions are very simple and require little explanation. Before an attribute can be used it must be initialized, and to clean up all memory associated with it the user must call destroy on it.

The function **globus\_xio\_attr\_cntl** manipulates values in the attribute. For more info on it see **globus\_xio\_attr\_cntl**.

## Author

Generated automatically by Doxygen for globus\_xio from the source code.