NAME

shmdefine − define shared memory regions

SYNOPSIS

shmdefine [ −b basename ] [ −U ] [ −N ] [ files ]

DESCRIPTION

The shmdefine utility provides a simple interface to the shared memory facility.  Shared memory regions are described to the utility using a small language.  The utility produces two files which are to be included when the program is linked (e.g. with f77(1)).  The linker command file describes the shared memory regions to the linker.  The initialization file contains an executable function to access the shared memory services at program start-up time.  The function is automatically called before the main program starts. 

Files are shmdefine source files.  If no files are specified, input is from the standard input. 

−b basename The names of the initialization file and the linker command file are constructed by appending .sm.c and .sm.ld, respectively, to the basename.  If no −b option is present, the basename defaults to "shm_init". 

−U Do not translate common block names.  Without this option, shmdefine translates FORTRAN common block names to lower case.  If the −U option is specified to f77(1), then it should also be specified here.

−N This option suppresses the initialization of variables in shared memory regions during execution of the initialization function.  If no −N option is present, shared memory variables such as "initialized" common blocks will be initialized in this function.  It is not necessary to use this option when the shared memory region is attached to I/O memory, for initialization will always be suppressed in this case. 

There can only be one initialization file in a program, so a single invocation of shmdefine typically defines all of the shared memory regions used by a program.  Each shared memory region is defined like this:

SHARED REGION regionname

attributes and variables for this region

END SHARED REGION

The external names s__regionname and e__regionname are reserved by the utility to define the start and end of the shared memory region. 

The input to the utility is free-form.  Blanks, tabs and newlines are ignored, except as separators.  A "#" indicates that the rest of the line is a comment, unless it is in a quoted filename. 

All of the attributes are optional.  The attributes that may be specified are:

ADDRESS=addr
The shared memory region begins at virtual address addr. Addr may be decimal, or octal (with a leading zero), or hexadecimal (with a leading "0x").  This attribute is needed only by programs that must have the shared memory region bound to a particular virtual address. 

IPC=(list)
The IPC specification allows the user control over the creation of the shared memory region. List is a comma-separated list of the following flags:

IPC_CREAT
The shared memory region is created if it does not already exist.

IPC_EXCL
Used with IPC_CREAT, this flag causes the program to get an error if the shared memory region already exists.

IPC_PRIVATE
The shared memory region is created, but is not accessible to any other processes, except via fork(2). This flag may not be used with the KEY= attribute.

SHM_LOCAL
Use SHM_LOCAL if the shared memory region is to be loaded into local memory. If SHM_LOCAL is set and SHM_HARD is not set, then the binding of the region is termed a "soft" binding. A soft binding allows pages to be allocated from global memory when pages are not available for allocation from the local memory pool. This flag has no effect on systems without local memory. See memory(7). 

SHM_HARD
Use SHM_HARD in addition to SHM_LOCAL if the shared memory region is to be loaded into local memory with a "hard" binding. A hard binding means that the calling process will receive a SIGSEGV signal if pages cannot be allocated from the local memory pool when needed. This flag has no effect on systems without local memory. See memory(7). 

SHM_IO
Use SHM_IO if the shared memory region is to be loaded into I/O memory. See shmbind(2). 

SHM_NCACHE
Use SHM_NCACHE if the shared memory region cannot be cached.  This parameter need not be specified for regions loaded into I/O memory (SHM_IO).  These regions are always cache-inhibited.

If no IPC attributes appear for a region, the default is IPC=(IPC_CREAT).  An empty list may be specified to turn off all of the flags, i.e., IPC=(). 

If an IPC specification appears, and IPC_CREAT is not specified, then the resulting program gets an error if the shared memory region does not exist. 

KEY="filename"
Filename is passed to ftok (see stdipc(3C)), at program start-up, to generate a key. The key is used with shmget(2) to identify the shared memory region to the system. All programs that refer to the same shared memory region must use the same key, and therefore the same key filename. Filename must refer to a file that exists when the program is started.  The position of the file in the file system is used to generate the key.  The contents of the file are not accessed or modified.  Note that if filename is a relative name, the key generated depends on the current working directory at the time the program is started. 

The filename must be enclosed in quotes.  Long filenames may be continued to the next line by preceding the newline with a backslash. 

If this attribute is not specified, the default filename is the name of the shared region. 

In some cases, it may be desirable to specify a key directly, without using ftok.  The form

KEY=int

may be used to specify a key that is not translated.  Int is an integer.  Int may be decimal, or octal (with a leading zero), or hexadecimal (with a leading "0x"). 

MODE=n
The permissions of the shared memory region are set to n, where n is assumed to be an octal number constructed from the logical OR of the following modes:

0400 read by owner

0200 write by owner

0040 read by group

0020 write by group

0004 read by others

0002 write by others

where the owner, group and others are the same as for referencing files in the file system.  If this attribute is not specified, the permissions default to 0644 (read by anyone, write only by the owner).  MODE is only significant if the shared memory region is being created (or might be created).  See IPC, above. 

SHM_RDONLY
Use SHM_RDONLY if the program should not be allowed to write into the shared memory region. Also, if a program is attempting to access a region that it has read access to, but which it doesn’t have write access to, then it must use SHM_RDONLY.

SHM_RDONLY refers to the attachment of a shared memory region to a particular process, not to the access permissions the region is created with. 

Variables in the region are FORTRAN common blocks, C external variables, or entire FORTRAN datapool dictionaries. 

FORTRAN COMMON common-block-name
The FORTRAN common block common-block-name is included in the current region. 

FORTRAN BLANK COMMON
The FORTRAN unnamed ("blank") common block is included in the current region.

C EXTERN external-name
The C external variable external-name is included in the current region. 

INCLUDE "filename"
The FORTRAN datapool dictionary object file filename is included in the current region. 

The variables are allocated in the region in the same order that they appear in the shmdefine source. 

The keywords and common block names may be specified in upper or lower case.  The C external names are case-significant.  Each C external name must be defined somewhere in the user program.  (Common blocks are implicitly defined.)  The datapool dictionary filenames may contain relative or absolute path information.  Each datapool dictionary filename appearing in an INCLUDE statement must have been previously created from a datapool definition file using f77(1).

C external variables that are in shared memory regions should be declared "volatile" in the C source. 

If you use f77(1), then any common blocks or datapools in shared memory regions need to be declared to be "VOLATILE" in the FORTRAN source.

The linker command file and initialization file may be used with multiple programs to ensure that the regions are defined the same way. 

EXAMPLE

Suppose we have two FORTRAN programs, WRITER and READER, in writer.f and reader.f, respectively, that communicate through a common block "ex" in a shared memory region.  They might both use this declaration in the FORTRAN source:

COMMON /ex/ IFLAG, IARRAY(5)
VOLATILE ex

and they might both use this file, say in "fort_ex.sm" as source to shmdefine:

SHARED REGION fort_ex

KEY="/usr/bob/key"
FORTRAN COMMON ex

END SHARED REGION

Then these programs might be built with the following commands:

shmdefine fort_ex.sm
cc −O −c shm_init.sm.c
f77 writer.f shm_init.sm.o shm_init.sm.ld −o writer
f77 reader.f shm_init.sm.o shm_init.sm.ld −o reader

FILES

shm_init.sm.c

shm_init.sm.ld Default output file names

SEE ALSO

f77(1), hf77(1), ipcrm(1), ipcs(1), ld(1), shmconfig(1M), shmbind(2), shmget(2), stdipc(3C), memory(7). 

For information about sharing Ada objects and FORTRAN or C objects using shared memory, see Shared Memory and Process Communication, in Part 1, Operations, of the CX/UX HAPSE Reference Manual, and the description of pragma interface_shared_object in the HAPSE Programmer’s Reference Manual. 

DIAGNOSTICS

Error messages from the utility are intended to be self-explanatory.  If there are any errors, then the output files are not produced and the exit status is non-zero. 

Errors in the initialization function produce error messages on standard error and cause the program to exit with a status of 255. 

WARNINGS

The number of shared memory regions that may exist concurrently in a system is limited.  When a shared memory region is no longer needed (e.g.  all programs using it have completed) it should be removed with ipcrm(1). Candidates for removal can be found by using ipcs(1).

CX/UX User’s Reference Manual