---
name: IO::Socket
runtime: pp
source: src/native/IO/Socket/pp.rs
---
```{index} single: IO::Socket; Perl module (pp runtime)
```

# IO::Socket

Native implementation of IO::Socket

Provides object-oriented socket operations compatible with Perl's IO::Socket.
This replaces the XS-based IO::Socket that ships with perl5.

IO::Socket inherits from IO::Handle.

Most methods are currently stubs that return plausible defaults, sufficient
for modules that probe socket capabilities without performing real I/O.

# Synopsis

    use IO::Socket::INET;

    # TCP client
    my $sock = IO::Socket::INET->new(
        PeerAddr => 'localhost',
        PeerPort => 8080,
        Proto    => 'tcp',
    ) or die "Cannot connect: $!";
    print $sock "GET / HTTP/1.0\r\n\r\n";

    # TCP server
    my $server = IO::Socket::INET->new(
        LocalPort => 8080,
        Listen    => 5,
        Proto     => 'tcp',
        ReuseAddr => 1,
    ) or die "Cannot listen: $!";

# Functions

## new

Constructor. Creates a new IO::Socket blessed hashref, storing any
key/value constructor arguments on the hash. In perl5 this delegates
to subclasses (IO::Socket::INET, IO::Socket::UNIX).

```perl
use IO::Socket;
my $sock = IO::Socket->new(Domain => AF_INET, Type => SOCK_STREAM);
```

## accept

Accepts an incoming connection. Stub: returns undef.

```perl
my $client = $sock->accept();
```

## bind

Binds the socket to an address. Stub: returns 1 (success).

```perl
$sock->bind($packed_addr);
```

## connect

Connects to a remote address. Stub: returns 0 (failure).

```perl
$sock->connect($packed_addr);
```

## listen

Starts listening for connections with the given backlog.
Stub: returns 1.

```perl
$sock->listen(5);
```

## shutdown

Shuts down part or all of the socket connection.
Stub: returns 1.

```perl
$sock->shutdown(2);
```

## peername

Returns the packed sockaddr of the remote end. Stub: returns undef.

```perl
my $addr = $sock->peername();
```

## sockname

Returns the packed sockaddr of the local end. Stub: returns undef.

```perl
my $addr = $sock->sockname();
```

## sockopt / getsockopt / setsockopt

Get or set socket options. `sockopt`/`getsockopt` return undef,
`setsockopt` returns 1.

```perl
$sock->setsockopt(SOL_SOCKET, SO_REUSEADDR, 1);
my $val = $sock->getsockopt(SOL_SOCKET, SO_REUSEADDR);
```

## sockdomain

Returns the socket domain. Stub: returns AF_INET (2).

```perl
my $domain = $sock->sockdomain();
```

## socktype

Returns the socket type. Stub: returns SOCK_STREAM (1).

```perl
my $type = $sock->socktype();
```

## protocol

Returns the protocol number. Stub: returns 0.

```perl
my $proto = $sock->protocol();
```

## timeout

Gets or sets the timeout value. When setting, returns the new value.
When getting, returns undef.

```perl
$sock->timeout(30);
my $t = $sock->timeout();
```

## connected

Returns the peer address if connected, undef otherwise.
Stub: returns undef.

```perl
if ($sock->connected) { ... }
```

## socket

Creates the underlying socket. Stub: returns 1.

```perl
$sock->socket(AF_INET, SOCK_STREAM, 0);
```

## socketpair

Creates a pair of connected sockets. Stub: returns 1.

```perl
$sock->socketpair(AF_UNIX, SOCK_STREAM, 0);
```

## atmark

Checks if the socket is at the out-of-band mark. Stub: returns 0.

```perl
if ($sock->atmark) { ... }
```

## send

Sends data on the socket. Stub: returns the length of the data argument.

```perl
$sock->send($data, $flags);
```

## recv

Receives data from the socket. Stub: returns undef.

```perl
$sock->recv($buf, 1024, $flags);
```