io_pipe(3)

✨ io_pipe(3) ✨

okay bestie, so this one lives in the Library Functions Manual and it's literally the origin story of every Unix pipe ever 💖

🌸 NAME 🌸

io_pipe — create a Unix pipe, that's it, that's the whole job 🫶

🎀 SYNTAX 🎀

#include <libowfat/io.h>

int io_pipe(int64 pfd[2]);

🦋 DESCRIPTION 🦋

io_pipe creates a brand new UNIX "pipe." ✨ A pipe can receive data and provide data — so like, any bytes you write into the pipe can then be read back out of the pipe, in the exact same order. first in, first out, no cap 👑

A pipe is typically stored in an 8192-byte memory buffer, but the exact number lowkey depends on the UNIX kernel — it's giving "your mileage may vary" 💅 Bytes get written to the end of the buffer and read from the beginning of the buffer. Once a byte has been read, it's eliminated from the buffer, which makes space for another byte to be written. So readers cannot "rewind" a pipe to read old data — there's no rewind button, bestie, the past is gone 🙈

Once 8192 bytes have been written to the buffer, the pipe will not be ready for further writing until some of the bytes have been read. And once all the bytes written have been read, the pipe will not be ready for further reading until more bytes are written. it's a whole balance situation ⚖️

io_pipe sets d[0] to the number of a new descriptor reading from the pipe, and sets d[1] to the number of a new descriptor writing to the pipe. Then it returns 1 to indicate success 🎉

If something goes wrong, io_pipe returns 0, setting errno to indicate the error. In that case it frees any memory that it allocated for the new pipe, and it leaves d alone — so no half-built pipe nonsense, it cleans up after itself like a functioning adult 💀

⚠️ heads up bestie: on the error path you get 0 back, errno gets set, the memory gets freed, and d stays untouched. don't go reading from d like it's real, okay? 😭

👑 SEE ALSO 👑

• io_readfile(3)
• io_createfile(3)
• io_socketpair(3)

and that's the whole page, fr fr 🌈 big slay to the Library Functions Manual for hosting io_pipe(3), mwah, go build a pipe, you've got this 🎀💖✨