---
name: "iostream"
section: "3"
platform: "linux"
package: "libnessus-dev"
version: "1.0.10-2"
release: "Debian 3.0 (Woody)"
platforms: ["linux"]
url: "https://new.carta.tech/iostream"
---

# iostream(3)

a transparent TCP layer

## NAME

io\_connect, io\_accept, io\_listen - a transparent TCP layer

## SYNOPSIS

```
#include <peks.h>

int send (unsigned fd, const char *data, unsigned len,
          unsigned flags);

int recv (unsigned fd, char *buffer, unsigned len,
          unsigned flags);

int shutdown (unsigned fd, unsigned how);

int close (unsigned fd);

int io_connect (const char* server, unsigned tcp_port);
int io_listen  (const char* bind_name, unsigned tcp_port);
int io_accept  (int socket);

int io_connect_timeout,io_accept_timeout,io_listen_backlog;
```

## DESCRIPTION

Make sure that the "**#include \<peks.h\>**" directive comes last of the include files. This include file replaces the functions **send()**, **recv()**, **shutdown()**, and **close()** by extended versions  **io\_send()**, **io\_recv()**, **io\_shutdown()**, and **io\_close()**.

By default, the extended versions of the io-functions just call the functions that they are hiding, passing arguments and returning the function value received.

Not until a cipher layer is (logically) pushed upon the io data stream, the extended io-functions become effective.  Pushing a cipher layer upon the io data stream is typically done transparently while the  session key is negotiated.

It may be nessary (but unlikely) that the cypher layer needs to be  removed, or popped from the io stream without closing it.  In that  case, the extended io-functions act as described before, just passing  arguments and return codes to and from the functions that they are  hiding.

**Io\_connect()** is a TCP convenience function wrapper around the **connect()** service from the operating system. The first argument *server* is the server name to connect to (see **gethostbyname**(2) for the name resolution) and the second argument *typ\_port* is TCP port on that server.

By setting the global variable *io\_connect\_timeout* to some positive value n (default is 20), some timeout is imposed on how long the system waits fo data.  This is unsally done by wating until the data arrive and installing an **alarm()** timer, while reading. So a signal **SIGALRM** will be sent after n seconds terminating a pending **connect()** call. Setting this variable to zero, this feature will be totally disabled, something negative allows to set a timeout (the absolute value of that) until the first data arrive, only.  In any case of a timeout, global variable **errno** is set to the value *EINTR*.

**Io\_listen()** is a TCP convenience function wrapper around the **listen()** service from the operating system. The first argument *bind\_name* is a host name, the listener binds an address to the listener socket (see [**bind**(2)](/bind/2.md) for details.) The second argument *tcp\_port* tells on which tcp port an incoming connection request is accepted (see [**listen**(2)](/listen/2.md) for details.)

By setting the global variable *io\_listen\_backlog* to some value n (default is 5), you can control how many connecting clients can be handled, simultaneously (see [**listen**(2)](/listen/2.md) for details.)

**Io\_accept()** is a TCP convenience function wrapper around the **accept()** service from the operating system. The function argument is a listener socket number as returned from **Io\_listen()**.

By setting the global variable *io\_accept\_timeout* to some positive value n (default is 5), a signal **SIGALRM** will be sent after n seconds terminating a pending **accept()** call. Setting this variable  to something non-positive, this feature will be disabled.

Example (client):

```

int socket ;

if ((socket = io_connect ("server.my.domain", 1234)) < 0)
return -1;
...

```

Example (server):

```

int socket, listen_socket ;

if ((listen_spcket = io_listen (0, 1234)) < 0)
return -1;
...

if ((socket = io_accept (listen_socket)) < 0)
return -1;
...

```

Note: It is safe, to use the "**#include \<peks.h\>**" directive all over the place provided this include directive comes last.

## RETURN VALUE

The functions **send()**, **recv()**, **shutdown()**, and **close()** behave as described in the manual(2) from the operating system.

Upon success, **Io\_connect()** and io\_accept() **return a open TCP** **socket number as described in connect***(2) and* **accept***(2),* *and* **Io\_listen()** *a listener socket as described in* **listen**.

Upon error, these functions return -1 while the global variable **errno** is set to indicate some explanation.

## SEE ALSO

[**listen**(2)](/listen/2.md), [**accept**(2)](/accept/2.md), [**connect**(2)](/connect/2.md), [**socket**(2)](/socket/2.md),  [**io\_push**(3)](/io_push/3.md), [**io\_send**(3)](/io_send/3.md), [**errno**(3)](/errno/3.md),  **peks-errnum**(3, [**gethostbyname**(3)](/gethostbyname/3.md),

## AUTHOR

The **peks** package where these functions belong to was written by Jordan Hrycaj \<jordan@teddy-net.com\>, originally to support the **nessus** security scanner.