# gizlang/client

A Wayland client over a Unix socket: the requests and events a window needs (the registry, a surface with a shared memory buffer, an xdg toplevel, the seat's pointer and keyboard). A message is a header of the object id and of its size and opcode, then its arguments in 32-bit words. A file descriptor travels beside the bytes, as ancillary data. The system calls are raw, and their numbers come from gizlang/linux for the ABI of this machine, so the same program runs on GizOS and on Linux, on each CPU that machine_syscall serves.

```gizlang
import * as Client from "gizlang/client";
```

## Types

### `Calls`

```gizlang
type Calls = { socket: i64; connect: i64; sendmsg: i64; recvmsg: i64; close: i64; memfd: i64; ftruncate: i64; mmap: i64; }
```

The wire numbers of the calls this client makes, on the ABI of this machine.

- `socket`: `i64`
- `connect`: `i64`
- `sendmsg`: `i64`
- `recvmsg`: `i64`
- `close`: `i64`
- `memfd`: `i64`
- `ftruncate`: `i64`
- `mmap`: `i64`

### `Event`

```gizlang
type Event = { object: i64; opcode: i64; at: i64; size: i64; }
```

An event of an object: its id, its opcode, and the address and size of its arguments (after the header). The
arguments stay valid until consume() takes the event off the input.

- `object`: `i64`
- `opcode`: `i64`
- `at`: `i64`
- `size`: `i64`

### `Global`

```gizlang
type Global = { id: i64; interfaceName: string; version: i64; }
```

A global of the registry: its name, its interface and its version.

- `id`: `i64`
- `interfaceName`: `string`
- `version`: `i64`

### `Client`

```gizlang
type Client = { fd: i64; out: i64; outUsed: i64; input: i64; inputUsed: i64; nextId: i64; scratch: i64; calls: Calls; fds: Vec<i64>; }
```

A connection: the socket, the outgoing and incoming buffers, the next object id, the scratch of the message headers
and the calls of this machine. The memory stays mapped for the connection's life.

- `fd`: `i64`
- `out`: `i64`
- `outUsed`: `i64`
- `input`: `i64`
- `inputUsed`: `i64`
- `nextId`: `i64`
- `scratch`: `i64`
- `calls`: `gizlang_wayland.Calls`
- `fds`: `Vec<i64>` — The descriptors that came with events (a keymap's, a selection's pipe), oldest first, until takeFd.

## Functions

### `calls`

```gizlang
function calls(): Calls
```

The calls of this machine, each number looked up once in the ABI that machine_syscall calls with. A call the ABI
lacks is -1, and connect() throws ENOSYS for it.

Effects: fail.

### `memory`

```gizlang
function memory(wire: Calls, count: i64): i64 throws i64
```

COUNT zeroed bytes of private memory, page-aligned; the process keeps them for its life. A failure throws its errno.

Effects: fail, read, write.

### `connect`

```gizlang
function connect(path: string): Client throws i64
```

A client connected to the compositor socket at PATH.

Effects: fail, read, write.

### `adopt`

```gizlang
function adopt(fd: i64): Client throws i64
```

A client on FD, the end of a connected socket the compositor gave the program in WAYLAND_SOCKET.

Effects: fail, read, write.

### `close`

```gizlang
function close(wire: Calls, fd: i64): void
```

Close descriptor FD (a shared memory file once the compositor has it).

Effects: read, write.

### `newId`

```gizlang
function newId(c: mut Client): i64
```

A new object id, for the object a request creates.

Effects: fail.

### `begin`

```gizlang
function begin(c: mut Client, object: i64, opcode: i64): i64
```

Start a message to OBJECT with OPCODE. Its arguments follow with the put functions, then end() closes it.

Effects: fail, write.

### `putNumber`

```gizlang
function putNumber(c: mut Client, value: i64): void
```

A 32-bit number: an unsigned id, a count, or a fixed-point value (24.8) as its 256ths.

Effects: fail, write.

### `putText`

```gizlang
function putText(c: mut Client, value: string): void
```

A string: its length with the NUL, its bytes, the NUL, then the padding to 32 bits.

Effects: fail, write.

### `end`

```gizlang
function end(c: mut Client, at: i64): void
```

Close the message that began at AT: its size goes into the header. It is sent by flush().

Effects: fail, read, write.

### `flush`

```gizlang
function flush(c: mut Client, fd: i64): void throws i64
```

Send the closed messages. FD, when not 0, travels with the first of them as ancillary data; the caller closes it.

Effects: fail, read, write.

### `next`

```gizlang
function next(c: mut Client): Event throws i64
```

The next event, reading the socket when no whole message is buffered. Take it off with consume() before the next
call. A read that fails throws its errno.

Effects: fail, read, write, alloc.

### `consume`

```gizlang
function consume(c: mut Client, event: Event): void
```

Take EVENT off the input once it is handled.

Effects: fail, read, write.

### `takeFd`

```gizlang
function takeFd(c: mut Client): i64
```

The descriptor of the event being read that carries one (wl_keyboard.keymap, wl_data_source.send): the oldest that
came; -1 when none did. Its taker closes it.

Effects: fail, alloc.

### `argUnsigned`

```gizlang
function argUnsigned(event: Event, offset: i64): i64
```

The 32-bit unsigned argument at OFFSET bytes into the event's arguments.

Effects: fail, read.

### `argSigned`

```gizlang
function argSigned(event: Event, offset: i64): i64
```

The 32-bit signed argument at OFFSET bytes into the event's arguments.

Effects: fail, read.

### `argText`

```gizlang
function argText(event: Event, offset: i64): string
```

The string argument at OFFSET bytes, without its NUL.

Effects: fail, read, alloc.

### `textBytes`

```gizlang
function textBytes(length: i64): i64
```

The bytes a string argument takes, from its length word (with the NUL) to the padding.

Effects: fail.

### `global`

```gizlang
function global(event: Event): Global
```

The global of a wl_registry.global event.

Effects: fail, read, alloc.

### `sharedMemory`

```gizlang
function sharedMemory(wire: Calls, count: i64): { fd: i64; at: i64; } throws i64
```

A shared memory file of COUNT bytes, mapped read and write: its descriptor and its address. A failure throws its
errno. The descriptor is for the compositor (create_pool), which then owns the memory with the client.

Effects: fail, read, write.

## Constants

### `DISPLAY`

```gizlang
const DISPLAY: i64 = 1
```

The object id of wl_display, the first object of every connection.

