USCONFIG(3P)USCONFIG(3P)NAMEusconfig - semaphore and lock arena configuration operations
C SYNOPSIS
#include <ulocks.h>
ptrdiff_t usconfig (int cmd, ...);
DESCRIPTIONusconfig is used to configure the use of semaphores and locks. Some of
these options set configurable parameters to be used on the next
usinit(3P), others give back information about a particular arena. In
the discussion below, arguments to usconfig are numbered starting from 1,
thus the first argument refers to cmd. Many of the options require an
arena pointer which is the value returned by a successful call to usinit
and is always interpreted as a usptr_t *.
The following cmds are available:
CONF_INITSIZE
Sets the shared segment size (in bytes) for semaphores, locks,
and the usmalloc(3P) arena to the value given by the second
argument interpreted as an unsigned int. The initial value is
65536 bytes. This only has effect if called before a usinit(3P).
It returns the previously set value.
CONF_INITUSERS
Sets the maximum number of users for a given group of semaphores
and locks to the value given by the second argument interpreted
as an unsigned int. The maximum allowable is 10000 users, and
the initial value is 8. This only has effect if called before
usinit(3P). Each process that calls usinit(3P) is considered a
user, as is each shared address process that uses a spinlock or
semaphore without calling usinit(3P). It returns the previously
set value.
CONF_GETSIZE
Returns the arena size (in bytes) for the arena specified by the
second argument interpreted as an usptr_t *. (as returned by
usinit(3P)).
CONF_GETUSERS
Returns the maximum number of users for the arena specified by
the second argument interpreted as an usptr_t *. (as returned by
usinit(3P)).
CONF_LOCKTYPE
The second argument interpreted as an unsigned int. defines
which of US_NODEBUG, US_DEBUG, or US_DEBUGPLUS locks are to be
used in the arena set up by the next call to usinit(3P). The
US_NODEBUG option is the fastest, and no debugging or metering
information is available. US_DEBUG locks provide metering and
Page 1
USCONFIG(3P)USCONFIG(3P)
debugging information about each lock transaction. The metering
information gathered consists of - the number of times the lock
is requested (lm_tries); the number of times the lock is acquired
(lm_hits); and the number of times the lock was found locked
(lm_spins). The metering is stored in a lockmeter_t structure
and is retrievable via usctllock(3P). The debugging information
maintained consists of the process id of the owner of the lock
(ld_owner_pid). The pid is set to -1 if no one owns the lock.
The debug info is stored in a lockdebug_t structure and is
retrievable via usctllock(3P). The US_DEBUGPLUS option provides
the same debugging and metering information and in addition, if
either an unset lock is unlocked, a set lock is unlocked by other
than the setter, or a lock is locked twice by the same caller, a
message is printed to stderr.
CONF_ARENATYPE
By default, arenas are configured so that unrelated processes may
join the arena by specifying the appropriate file name when
calling usinit(3P). This means that the file must continue to
exist for the duration of the time the arena is in use. If the
file is a temporary file, it may be difficult for an application
program to guarantee the file gets removed at the appropriate
time. If the second argument interpreted as an unsigned int. is
set to US_SHAREDONLY then usinit(3P) will unlink the file after
it has opened it. This of course means that unrelated processes
may NEVER join the arena. This also implies that all users of
the arena must be sharing file descriptors, either by using the
PR_SFDS option to sproc(2)), or being related via fork(2). Note
however that processes related via fork share file descriptors
only at fork time, thus the arena must be set up by the parent
process before any children are spawned. Note that if a child is
spawned before an arena is set up, and the arena type is set to
US_SHAREDONLY and both the parent and child call usinit on the
same filename, they will get separate arenas - probably not the
desired result.
CONF_CHMOD
Sets the access permissions on the arena and lock files. When
usinit(3P) creates an arena, the user and group ids are set to
the callers effective user and group id, and the access
permissions are set to 0600. This makes the arena available only
to processes running with the same effective user id. To allow
other user or group ids access to the arena, the mode on the
various files and locks may be changed by using the CONF_CHMOD
option. The second argument, interpreted as an usptr_t *.
specifies which arena, and the third argument, interpreted as an
mode_t specifies the new mode (see chmod(2)). Access to pollable
semaphores is governed on a per semaphore basis and is set when
first opening the semaphore via usopenpollsema(3P).
Page 2
USCONFIG(3P)USCONFIG(3P)
CONF_ATTACHADDR
Sets the virtual address where the arena and locks are attached
in the calling process to the value specified by the second
argument, taken as a void *. It must be a multiple of the
underlying page size (see getpagesize(2)). Normally, when
usinit(3P) is called, the arena and lock area are attached (via
mmap(2)) using the option that lets the system pick an
appropriate attach address. This may not be appropriate if the
original creator of the arena is a small process (small code
space) and a very large code space unrelated process attempts to
attach to the arena. This option allows the creator to fix an
address that is acceptable to all processes wishing to join the
arena. Note that it is important after calling usinit(3P) to
reset the attach address to the initial value ((void *) ~0)
before another usinit(3P) is called. Otherwise the second call
will fail. When sproc(2) is called, an arena used to protect
standard I/O is set up automatically. By specifying a new attach
address before first calling sproc(2) the location of the I/O
arena may be fixed. This only has effect if called before a
usinit(3P). It returns the previously set value.
CONF_AUTOGROW
If the second argument, interpreted as an unsigned int, is zero
then the underlying file of a newly created arena will be grown
to its maximum size (as specified by CONF_INITSIZE) before the
arena is mapped in. The arena will be mapped without the
MAP_AUTOGROW option to mmap(2). If the second argument is non-
zero the file will be mapped with the MAP_AUTOGROW option. This
can cause some unexpected failures if the underlying file system
fills up. The default is to map all files with the MAP_AUTOGROW
option. This only has effect if called before a usinit(3P). It
returns the previously set value.
CONF_AUTORESV
If the second argument, interpreted as an unsigned int, is non-
zero then the arena file will be mapped in with the MAP_AUTORESRV
option to mmap(2). This option is only effective when auto-
growing the arena (see CONF_AUTOGROW above) and the arena file is
the special device /dev/zero. These two options together permit
declaring arenas that are very large on systems with limited
resources, and only encountering errors if in fact the
application actually uses too much memory. This only has effect
if called before a usinit(3P). It returns the previously set
value.
CONF_HISTON
Enable semaphore history logging for the arena given by the
second argument interpreted as an usptr_t *. The history
mechanism may then be enabled for previously allocated semaphores
using usctlsema(3P). All subsequent semaphores allocated via
usnewsema(3P) are set to log their history. This cmd serves as a
global flag on the history mechanism in conjunction with
Page 3
USCONFIG(3P)USCONFIG(3P)
CONF_HISTOFF to allow for quick enabling and disabling of
history. The history mechanism logs the operation, the semaphore
for which the operation was done, the pid of the process
performing the operation, and the address from which the
operation was called. No history is maintained for locks, since
the number of transactions on locks is typically large.
CONF_HISTSIZE
Set the maximum number of history records kept for the arena
specified by the second argument interpreted as an usptr_t *. to
the value of the third argument, interpreted as an unsigned int.
If set to 0 (the initial value) then new history records are
allocated until there is no more room in the arena.
CONF_HISTFETCH
Fills in a history structure for the arena specified by the
second argument interpreted as an usptr_t *. The third argument,
interpreted as a histptr_t *, should point to storage where the
history data can be copied to. This structure contains - the
number of entries in the history list ( hp_entries); a pointer to
the most recent history structure ( hp_current); and the number
of non-logged entries due to either lack of space or exceeding
the maximum number of entries specified by CONF_HISTSIZE(
hp_errors). The history list is a doubly linked and NULL
terminated list so that the user can then traverse the list as
they see fit. Traversing the list from hp_current through h_last
will access the list from most recent semaphore event to least
recent. If no more space is available in the arena, the oldest
history event is re-used. The hist_t structure (defined in
<ulocks.h>) is described below.
CONF_HISTOFF
Disable the history mechanism for all semaphores in the arena
specified by the second argument interpreted as an usptr_t *.
Note that this simply turns off a global history flag for the
given arena - the individual semaphores' history state is
unaffected.
CONF_HISTRESET
Reinitializes the history chain for the arena specified by the
second argument interpreted as an usptr_t *. to contain no
entries. This frees all previously allocated history records.
CONF_STHREADIOOFF
By default, the stdio(3) routines available with libc.a are
single threaded. Multiple shared address space processes may
attempt to execute them simultaneously and the system guarantees
that they will work as expected. This requires that the stdio(3)
data structures be locked on each access, thereby adding overhead
which may be unnecessary in certain applications. This command
turns off any single threading of the following routines: getc,
putc, fgetc, fputc, ungetc, getw, putw, gets, fgets, puts, fputs,
Page 4
USCONFIG(3P)USCONFIG(3P)
fopen, fdopen, freopen, ftell, rewind, feof, clearerr, ferror,
setbuf, setlinebuf, setbuffer, setvbuf, fclose, fflush, fread,
fwrite, fseek, fgetpos, fsetpos, flockfile, funlockfile, tempnam,
tmpnam, tmpfile, mktemp, mkstemp, popen, pclose, atexit, printf,
fprintf, vprintf, vfprintf, scanf, fscanf, The previous state of
stdio(3) single threading is returned.
Note: for FORTRAN the default is different, see CONF_STHREADIOON
below.
CONF_STHREADIOON
This option enables single threading of the stdio(3) routines.
The previous state of stdio(3) single threading is returned.
Note: The FORTRAN I/O library is not safe for multi-processing,
even if the stdio(3) routines are single threaded. For this
reason, FORTRAN programs have CONF_STHREADIOOFF configured by
default, to avoid the extra overhead. If a FORTRAN program
wishes to use the stdio(3) routines to get parallel I/O, you must
set CONF_STHREADIOON to re-enable the single threading.
CONF_STHREADMISCOFF
Some routines besides stdio(3) routines are also single threaded
by default. This option disables this for the following
routines: opendir, readdir, scandir, seekdir, closedir, telldir,
dup2, srand, rand, addsev, addseverity, fmtmsg, setcat, gettxt,
lfmt, localeconv, nl_langinfo, pfmt, setlabel, setlocale,
strftime, strxfrm, strcoll, vlfmt, vpfmt The previous state of
single threading is returned.
CONF_STHREADMISCON
This option enables single threading of the miscellaneous
routines mentioned above. This command is the inverse of
CONF_STHREADMISCOFF. The previous state of single threading of
the miscellaneous routines is returned.
CONF_STHREADMALLOCOFF
The malloc(3) routines are single threaded by default. This
option disables single threading for the following routines:
malloc, free, realloc, calloc, mallopt, mallinfo. The previous
state of their single threading is returned.
CONF_STHREADMALLOCON
This option enables single threading of the malloc(3) routines.
The previous state of single threading is returned.
The CONF_INITSIZE, CONF_ARENATYPE, CONF_AUTOGROW, CONF_AUTORESV,
CONF_ATTACHADDR, CONF_LOCKTYPE, and CONF_INITUSERS only take effect if
the caller is the process that first sets up the arena. If the process
is just joining an existing arena, the settings of these parameters is
ignored.
Page 5
USCONFIG(3P)USCONFIG(3P)
The structure declaration of hist_t is:
typedef struct {
struct usema_s *h_sem; /* the semaphore */
int h_op; /* the operation */
pid_t h_pid; /* the thread process id */
int h_scnt; /* the value of the semaphore */
pid_t h_wpid; /* the waking process id */
char *h_cpc; /* the calling PC */
struct hist_s *h_next; /* the next hist_t in the chain */
struct hist_s *h_last; /* the previous hist_t in the chain */
} hist_t;
h_sem is the address of the semaphore. h_next and h_last are the
linkages that chain all the history records together. h_op defines what
operation was performed on the semaphore. Valid operation types are
defined in <ulocks.h>. h_pid is the process id of the caller making the
semaphore call. h_scnt is the semaphore count at the end of the
operation. For the HOP_PWOKE operation type, the count is the current
semaphore count at the time the process ran after being woken. Pollable
semaphores will never record a HOP_PWOKE event. h_wpid is the process id
of the process to next receive the semaphore. It is only valid for the
HOP_VWAKE operation. h_cpc is the address in the callers code that the
semaphore operation was called from.
The structure declaration of histptr_t is:
typedef struct histptr_s {
hist_t *hp_current; /* pointer to the last hist_t */
int hp_entries; /* count of hist_t structs */
int hp_errors; /* # of errors due to lack of space */
} histptr_t;
usconfig will fail if one or more of the following are true:
EINVAL cmd is not a valid command.
EINVAL cmd is equal to CONF_INITSIZE and the second argument is less
than the system-imposed minimum (4096 bytes) or greater than
the system-imposed maximum size for a mapped memory segment.
EINVAL cmd is equal to CONF_INITUSERS and the second argument is
greater than the system-imposed maximum (10000).
EINVAL cmd is equal to CONF_ARENATYPE and the second argument is not
equal to either US_SHAREDONLY or US_GENERAL.
EINVAL cmd is equal to CONF_HISTFETCH and history is not currently
enabled.
Page 6
USCONFIG(3P)USCONFIG(3P)SEE ALSOchmod(2), usctllock(3P), usctlsema(3P), usinit(3P), usinitlock(3P),
usinitsema(3P), usmalloc(3P), usnewlock(3P), usnewsema(3P),
usnewpollsema(3P).
DIAGNOSTICS
Upon successful completion, the return value is dependent on the
particular command. CONF_AUTORESV, CONF_AUTOGROW, CONF_ATTACHADDR,
CONF_STHREADMALLOCOFF, CONF_STHREADMALLOCON, CONF_STHREADMISCOFF,
CONF_STHREADMISCON, CONF_STHREADSTDIOOFF, CONF_STHREADSTDIOON,
CONF_HISTRESET, CONF_HISTSIZE, CONF_HISTON, CONF_HISTOFF, CONF_GETSIZE,
and CONF_GETUSERS never return an error. Otherwise, a value of -1 is
returned and errno is set to indicate the error.
Page 7
