omirr(4)

NAME

omirr - online mirror kernel log device

SYNOPSIS

/proc/omirr

#include <linux/omirr.h>

int open("/proc/omirr", int oflag);

ssize_t read(int fildes, void *buf, size_t nbyte);

int ioctl(int fildes, int request, /* arg */ ...);

AVAILABILITY

Linux

DESCRIPTION

/proc/omirr is a special device in the Linux /proc filesystem used by the in.omirrd(8) daemon to receive notifications about file system modifications. /proc/omirr supports the system calls open(2), read(2), select(2), ioctl(2) and close(2).

The /proc/omirr device may be opened only once concurrently. Therefore a second attempt to open the device blocks the calling process unless O_NONBLOCK is specified in oflags. The device can only be opened in read-only mode, so O_RDONLY must be passed in the oflags.

open() accepts the following omirr-specific oflags:

O_NONBLOCK

An open will return without delay even if /proc/omirr is already open. In addition, this flag may affect subsequent reads (see below).

O_TRUNC

The data already available to be read will be discarded.

The behavior of read() is also modified by the O_NONBLOCK flag. If set, either via open(2) or by a fcntl(2) call, and there is no data available, a read attempt returns -1 with errno set to EAGAIN. If not set, the read() call blocks until data is available. When data is available, read() succeeds and returns the number of bytes actually read and placed in the buffer; this number may be less than the number of bytes requested in the read() call.

/proc/omirr defines the following device-specific ioctl() calls, which are defined in <linux/omirr.h>:

OMIRRCLEARBUF

discards the data which is currently available for reading. The ioctl arg is ignored.

OMIRRGETBLOCKMODE

returns the current value of the block-mode. The ioctl arg is of type (unsigned char *). It is used to return the block-mode value. If block-mode is set, the ring buffer holding the log data cannot overflow, because the process generating the new notification is blocked. If block-mode is not set, the ring-buffer overflow will be detected and logged with a special protocol operation. Block-mode is unset by default.

OMIRRSETBLOCKMODE

sets block-mode to the value of arg, of type (unsigned char). See OMIRRGETBLOCKMODE, above, for a description of block-mode.

OMIRRGETBUFCOUNT

returns the number of bytes available for read. arg is of type (unsigned long *).

OMIRRGETDONTLOGMASK

returns the current value of the don't-log-mask. The ioctl arg is of type (unsigned long *). It is used to return the mask value. The following bits are defined in the mask:

OMIRR_DONTLOG_PROC

suppress logging of file operations by the process which opened /proc/omirr

OMIRR_DONTLOG_PPROC

suppress logging of file operations by the parent of the process which opened /proc/omirr

OMIRR_DONTLOG_PGRP

suppress logging of file operations by the processes which are in the process group of the process which opened /proc/omirr

OMIRRSETDONTLOGMASK

sets the don't-log-mask to the value of arg, of type (unsigned long). See OMIRRGETDONTLOGMASK, above, for a description of the don't-log-mask.

RETURN VALUES

open(), read(), select(), ioctl() and close() return the values described in the manual pages open(2), read(2), select(2), ioctl(2) and close(2), respectively. Upon encountering an error, -1 is returned with the errno variable set accordingly.

ERRORS

In addition to the conditions listed in open(2), open() can fail if one of the following conditions specific to the /proc/omirr device is met:

EINVAL

An open mode of O_WRONLY or O_RDWR was specified.

EWOULDBLOCK

O_NONBLOCK is set and the /proc/omirr is already open.

EINTR

A signal was caught during the open() function.

In addition to the conditions listed in read(2), read() can fail if one of the following conditions specific to the /proc/omirr device is met:

EAGAIN

Non-blocking I/O has been selected using O_NONBLOCK and no data was immediately available for reading from /proc/omirr.

EINTR

A signal was caught during the read operation and no data was transferred.

ioctl() can fail on the following conditions special to the /proc/omirr device:

EINVAL

request or arg is not valid for this device.

FILES

/proc/omirr

omirr special proc filesystem device.

SEE ALSO

in.omirrd(8), open(2), read(2), select(2), ioctl(2), close(2), fcntl(2)

DIAGNOSTICS

omirr_log: buffer full - sleeping

is an information message generated if block-mode is set and a process generating a new notification is put to sleep, because the notification does not fit into the ring buffer.

omirr: setting block mode without OMIRR_DONTLOG_PROC may result in dead lock

WARNINGS

It is dangerous to switch on block-mode without including OMIRR_DONTLOG_PROC in the don't-log-mask, because that may result in a dead-lock condition where the process that opened /proc/omirr is blocked in a file system operation because the ring buffer is full, and is therefore unable to read data from the ring buffer. To warn about this condition, the kernel generates a warning message, see DIAGNOSTICS, above.

AUTHOR

Andreas Luik <[email protected]>