Man page of EVENTCOUNTER

Section: The seqev Library (3) Updated: RELEASE 4.15

NAME

create_eventcounter, eawait, eread, eadvance, rm_eventcounter - eventcounter operations  

SYNTAX

#include <seqev.h>

eventcounter_t *create_eventcounter (key_t key);

int eawait (eventcounter_t *eventcounter, long value);
long eread (eventcounter_t *eventcounter);
int eadvance (eventcounter_t *eventcounter);
int rm_eventcounter (eventcounter_t *eventcounter);

DESCRIPTION

create_eventcounter creates and initializes an eventcounter with the specified key. On success it returns a pointer to a newly allocated event counter. On failure, NULL is returned, and the value of errno is set to an appropriate value to indicate the error. In case the event counter already exists a valid pointer is returned, but no further initialization is done.

eawait blocks until the event counter becomes equal to or greater than the given value.

eread returns the current value of the event counter.

eadvance increments the event counter by one, possibly allowing processes waiting on the eventcounter to continue. In case eadvance causes an overflow of the event counter -1 will be returned and errno will be set to ERANGE.

rm_eventcounter removes the specified event counter.  

DIAGNOSTICS

In case of failure, create_eventcounter returns NULL and all other functions return -1. All functions can set errno to one of the following values before returning an error code.
[EINVAL]
The event counter does not have a valid event counter ID.
[EACCES]
The calling process does not have the required permission.

create_eventcounter can set errno to the following values:

[ENOSPC]
An attempt to create a new event counter ID exceeded the system-wide limit on the size of the according table.
[EPERM]
The calling process does not have the required effective user ID.
[EFAULT]
An error occured during initializing the event counter.
[ENOMEM]
The system does not have enough memory to complete the function.
[EEXIST]
An event counter ID already exists for the key parameter.
[EMFILE]
An attempt to attach the event count's shared memory region exceeded the maximum umber of attached regions allowed for any one process.
[ENOSYS]
The requested operation is not supported by this implementation.
[EINTR]
The function was interrupted by a signal.
[EIDRM]
The event counter was removed from the system.

eawait can set errno to the following values:

[EAGAIN]
Too many processes are already waiting for an event.
[EINTR]
The function was interrupted by a signal.
[ENOSYS]
The requested operation is not supported by this implementation.
[EIDRM]
The event counter was removed from the system.
[ERANGE]
An overflow of the event counter occured.
[ENOSPC]
The system-defined limit on the number of processes using this call was exceeded.

eread can set errno to the following values:

[EINTR]
The function was interrupted by a signal.
[ENOSYS]
The requested operation is not supported by this implementation.
[EIDRM]
The event counter was removed from the system.
[ENOSPC]
The system-defined limit on the number of processes using this call was exceeded.

eadvance can set errno to the following values:

[EINTR]
The function was interrupted by a signal.
[ENOSYS]
The requested operation is not supported by this implementation.
[EIDRM]
The event counter was removed from the system.
[ERANGE]
An overflow of the event counter occured.
[ENOSPC]
The system-defined limit on the number of processes using this call was exceeded.

rm_eventcounter can set errno to the following values:

[EPERM]
The calling process does not have the required effective user ID.
[ENOMEM]
The system does not have enough memory to complete the function.
 

COMPILING

Compiling has do be done with -lseqev e.g.

c89 program.c -lseqev  

RESTRICTIONS

Since event counters are implemented with semaphores and shared memory, they will interfere with semaphores and shared memory of the same key, leading to undefined behaviour. Also, sequencers with the same key cannot be used at the same time.

The number of processes, which can do an eawait on the same event counter simultaneously, is limited by SEMMSL (defined in /usr/include/sys/sem.h). In case additional processes want to do an eawait on the specified event counter, -1 will be returned and errno will be set to EAGAIN.

Event counters (like semaphores and shared memory) are not deleted when the last process that references them terminates. Therefore the last process has to call rm_eventcounter before terminating.

In case of unintended termination of the program use ipcs to find the corresponding semaphores and shared memory segments and ipcrm to remove them.  

ENVIRONMENT

The environment variable DEBUGEVENTCOUNTER may be used to define the current debuglevel. Currently there are two bits used, bit 0 for some debugging output in case of encountered errors, bit 1 for causing a core dump in case of an error. If DEBUGEVENTCOUNTER is defined, but contains no value the default debuglevel 1 (bit 0 set) is used. You may use several debug levels simultaneously by setting the apropriate bits in the the value assigned to DEBUGEVENTCOUNTER.  

SEE ALSO

Eventcounter(3), sequencer(3), Sequencer(3), ipcs(3), ipcrm(3)  

AUTHORS

Implementation by Günther Leber, modified by Alexander Vrchoticky.

Manual page by Peter Holzer and Günther Leber, modified by Alexander Vrchoticky and Thomas Galla. Cleaned-up by Thomas Perl.

Many thanks to Peter P. Puschner and Ralph Zainlinger, who tested the implementation.