USCONFIG(3P) USCONFIG(3P) NAME usconfig - semaphore and lock arena configuration operations C SYNOPSIS #include <ulocks.h> ptrdiff_t usconfig (int cmd, ...); DESCRIPTION usconfig 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 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). 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 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, 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. 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. SEE ALSO chmod(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