Chapter 3. Communicating with userland
Prev |  | Next

## Chapter 3. Communicating with userland

Instead of reading (or writing) information directly from kernel memory, procfs works with call back functions for files: functions that are called when a specific file is being read or written. Such functions have to be initialised after the procfs file is created by setting the `read_proc` and/or `write_proc` fields in the struct proc_dir_entry* that the function `create_proc_entry` returned:

    struct proc_dir_entry* entry;

    entry->read_proc = read_proc_foo;
    entry->write_proc = write_proc_foo;

If you only want to use a the `read_proc`, the function `create_proc_read_entry` described in the section called “Convenience functions” may be used to create and initialise the procfs entry in one single call.

## Reading data

The read function is a call back function that allows userland processes to read data from the kernel. The read function should have the following format:

`int read_func(` | char* | buffer,
| char** | start,
| off_t | off,
| int | count,
| int* | peof,
| void* | data`)`;

The read function should write its information into the `buffer`, which will be exactly `PAGE_SIZE` bytes long.

The parameter `peof` should be used to signal that the end of the file has been reached by writing `1` to the memory location `peof` points to.

The `data` parameter can be used to create a single call back function for several files, see the section called “A single call back for many files”.

The rest of the parameters and the return value are described by a comment in `fs/proc/generic.c` as follows:

> You have three ways to return data:

> 1. Leave `*start = NULL`. (This is the default.) Put the data of the requested offset at that offset within the buffer. Return the number (`n`) of bytes there are from the beginning of the buffer up to the last byte of data. If the number of supplied bytes (`= n - offset`) is greater than zero and you didn't signal eof and the reader is prepared to take more data you will be called again with the requested offset advanced by the number of bytes absorbed. This interface is useful for files no larger than the buffer.

> 2. Set `*start` to an unsigned long value less than the buffer address but greater than zero. Put the data of the requested offset at the beginning of the buffer. Return the number of bytes of data placed there. If this number is greater than zero and you didn't signal eof and the reader is prepared to take more data you will be called again with the requested offset advanced by `*start`. This interface is useful when you have a large file consisting of a series of blocks which you want to count and return as wholes. (Hack by Paul.Russell@rustcorp.com.au)

> 3. Set `*start` to an address within the buffer. Put the data of the requested offset at `*start`. Return the number of bytes of data placed there. If this number is greater than zero and you didn't signal eof and the reader is prepared to take more data you will be called again with the requested offset advanced by the number of bytes absorbed.

Chapter 5, Example shows how to use a read call back function.

Prev |  | Next
Removing an entry | Home | Writing data