Man page of SEQUENCER

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

NAME

create_sequencer, sticket, rm_sequencer - sequencer synchronization primitive  

SYNTAX

#include <seqev.h>

sequencer_t *create_sequencer (key_t key);

long sticket(sequencer_t *sequencer);
int rm_sequencer(sequencer_t *sequencer);

DESCRIPTION

create_sequencer creates and initializes a sequencer with the specified key. On success it returns a pointer to a newly allocated sequencer. On failure, NULL is returned and the value of errno is set to an appropriate value to indicate the error. In case the sequencer already exists a valid pointer is returned, but no further initialisation will be done.

sticket returns the number of previous sticket calls with the given parameter.

rm_sequencer removes the specified sequencer.  

DIAGNOSTICS

create_sequencer returns NULL in case of an error, whereas rm_sequencer and sticket return -1 if an error has occurred. In case of an error all functions set errno to an appropriate value. The following values of errno can be set by any of those functions:
[EINVAL]
The sequencer does not have a valid sequencer ID.
[EACCES]
The calling process does not have the required permission.

create_sequencer can set errno to one of the following values:

[ENOSPC]
An attempt to create a new sequencer 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 sequencer.
[ENOMEM]
The system does not have enough memory to complete the function.
[EEXIST]
An sequencer ID already exists for the key parameter.
[EMFILE]
An attempt to attach the sequencer's shared memory region exceeded the maximum number 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 sequencer was removed from the system.

sticket 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 sequencer was removed from the system.
[ERANGE]
An overflow of the sequencer occured.
[ENOSPC]
The system-defined limit on the number of processes using this call was exceeded.

rm_sequencer 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 to be done with -lseqev e.g.

c89 program.c -lsequev  

RESTRICTIONS

Since this implementation uses shared memory and semaphores, the existence of shared memory or semaphores with the same key leads to undefined behavior. Sequencers and Eventcounters with the same key cannot be used at the same time.

Sequencers are not removed automatically when the corresponding processes die. Therefore Sequencers must be deleted by the last process that references them before terminating. In case of unintended termination of the program use ipcs to find and ipcrm to delete the used semaphores and shared memory segments.  

ENVIRONMENT

The environment variable DEBUGSEQUENCER 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 DEBUGSEQUENCER 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 DEBUGSEQUENCER.  

AUTHOR

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

Manual page by Peter Holzer. Cleaned-up by Thomas Perl.

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

SEE ALSO

Sequencer(3), eventcounter(3), Eventcounter(3), ipcs(1), ipcrm(1)