creatsem(S)                    6 January 1993                    creatsem(S)


 Name

    creatsem - creates an instance of a binary semaphore

 Syntax


    cc  . . .  -lx


    int creatsem (sem_name, mode)
    char *sem_name;
    int mode;


 Description

    creatsem defines a binary semaphore named by semname to be used by
    waitsem(S) and sigsem(S) to manage mutually exclusive access to a
    resource, shared variable, or critical section of a program.  creatsem
    returns a unique semaphore number, semnum, which may then be used as the
    parameter in waitsem and sigsem calls.  Semaphores are special files of 0
    length.  The filename space is used to provide unique identifiers for
    semaphores.  mode sets the accessibility of the semaphore using the same
    format as file access bits. Access to a semaphore is granted only on the
    basis of the read access bit; the write and execute bits are ignored.

    A semaphore can be operated on only by a synchronizing primitive, such as
    waitsem or sigsem, by creatsem which initializes it to some value, or by
    opensem which opens the semaphore for use by a process.  Synchronizing
    primitives are guaranteed to be executed without interruption once
    started.  These primitives are used by associating a semaphore with each
    resource (including critical code sections) to be protected.

    The process controlling the semaphore should issue:

       semnum = creatsem(semaphore, mode);

    to create, initialize, and open the semaphore for that process.  All
    other processes using the semaphore should issue:

       semnum = opensem(semaphore);

    to access the semaphore's identification value.  Note that a process can-
    not open and use a semaphore that has not been initialized by a call to
    creatsem, nor should a process open a semaphore more than once in one pe-
    riod of execution.  Both the creating and opening processes use waitsem
    and sigsem to use the semaphore semnum.

 Diagnostics

    creatsem returns the value -1 if an error occurs.  errno is set under
    these conditions:

    [EEXIST]    The semaphore named by semname is already open for use by
                other processes.

    [ENAVAIL]   The semaphore has not been initialized by a call to creatsem.

    [ENOTNAM]   The file specified exists but is not a semaphore type.


 Notes

    After a calling creatsem, use waitsem to gain control of a given
    resource.

 See also

    opensem(S), sigsem(S), waitsem(S)

 Compatibility

    creatsem can only be used to define UNIX version 3.0 type semaphores, not
    UNIX System V type semaphores.

    This feature is a XENIX specific enhancement and may not be present in
    all UNIX implementations.

 Standards conformance

    creatsem is an extension of AT&T System V provided by the Santa Cruz
    Operation.