See, it's a full blown, working and compilable example. Don't hesitate to compile it yourself and test it, it really works. You should call the program from a terminal like this:

Now, let's focus on the read call itself:

The read signature is the following (extracted from Linux man-pages):

First, the fd argument represents the file descriptor. I have explained a bit this concept in my fork article.  A file descriptor is a int representing an open file, socket, pipe, FIFO, device, well it's a lot of things where data can be read or written, generally in a stream-like way. I'll go more in depth about that in a future article.

open function is one of the way to tell to Linux: I want to do things with the file at that path, please find it where it is and give me access to it. It will give you back this int called file descriptor and now, if you want to do anything with this file, use that number. Don't forget to call close when you're done with the file, as in the example.

So you need to provide this special number to read. Then there's the buf argument. You should here provide a pointer to the array where read will store your data. Finally, count is how many bytes it will read at most.

The return value is of ssize_t type. Weird type, isn't it? It means “signed size_t”, basically it's a long int. It returns the number of bytes it successfully reads, or -1 if there's a problem. You can find the exact cause of the problem in the errno global variable created by Linux, defined in . But to print an error message, using perror is better as it prints errno on your behalf.

In normal files - and only in this case - read will return less than count only if you have reached the file's end. The buf array you provide must be big enough to fit at least count bytes, or your program may crash or create a security bug.

Now, read is not only useful for normal files and if you want to feel its super-powers - Yes I know it's not in any Marvel's comics but it has true powers - you will want to use it with other streams such as pipes or sockets. Let's take a look on that:

Linux special files and read system call

The fact read works with a variety of files such as pipes, sockets, FIFOs or special devices such as a disk or serial port is what makes it really more powerful. With some adaptations, you can do really interesting things. Firstly, this means you can literally write functions working on a file and use it with a pipe instead. That's interesting to pass data without ever hitting disk, ensuring best performance.

However this triggers special rules as well. Let's take the example of a reading a line from terminal compared to a normal file. When you call read on a normal file, it only needs few milliseconds to Linux to get the amount of data you request.

But when it comes to terminal, that's another story: let's say you ask for an username. The user is typing in terminal her/his username and press Enter. Now you follow my advice above and you call read with a big buffer such as 256 bytes.

If read worked like it did with files, it would wait for the user to type 256 characters before returning! Your user would wait forever, and then sadly kill your application. It's certainly not what you want, and you would have a big problem.

Okay, you could read one byte at a time but this workaround is terribly inefficient, as I told you above. It must work better than that.

But Linux developers thought read differently to avoid this problem:

• When you read normal files, it tries as much as possible to read count bytes and it will actively get bytes from disk if that's needed.
• For all other file types, it will return as soon as there's some data available and at most count bytes:
  1. For terminals, it's generally when the user presses Enter key.
  2. For TCP sockets, it's as soon as your computer receives something, doesn't matter the amount of bytes it gets.
  3. For FIFO or pipes, it's generally the same amount as what the other application wrote, but the Linux kernel can deliver less at a time if that's more convenient.

So you can safely call with your 2 KiB buffer without staying locked up forever. Note it can also get interrupted if the application receives a signal. As reading from all these sources can take seconds or even hours - until the other side decides to write, after all - being interrupted by signals allows to stop staying blocked for too long.

This also has a drawback though: when you want to exactly read 2 KiB with these special files, you'll need to check read's return value and call read multiple times. read will rarely fill your whole buffer. If your application uses signals, you'll also need to check if read failed with -1 because it was interrupted by a signal, using errno.

Let me show you how it can be interesting to use this special property of read: