setmemwindow(1M) setmemwindow(1M)
NAME [Toc] [Back]
setmemwindow - changes the window id of a running program or starts a
program in a particular memory window
SYNOPSIS [Toc] [Back]
setmemwindow [ -cjnfbov ] [ -i WinId ]
-p pid | program [ arg ...]
DESCRIPTION [Toc] [Back]
setmemwindow is the command that changes the window id of a running
process or starts a specified program in a particular memory window.
If the -p option is specified with a non-zero pid, only the process'
window id is changed, and any value specified for program is ignored.
The executable program is only executed if the process id pid is
either 0 or unspecified.
Changing the window id for the running process does not mean the
process immediately attaches to or creates objects using that window.
The targeted process does not begin using the window until it exec's a
new image.
setmemwindow, used as a wrapper for an existing executable, starts the
program in the desired (see -i option below) memory window. In order
to execute program, setmemwindow changes the window id, fork's a child
and exec's program in the child process. The default behavior of
setmemwindow is to wait until program finishes. If -n is specified,
the waiting for program is bypassed and setmemwindow exits immediately
after fork'ing the child.
If -c and -j are unspecified, the default behavior is to place the
process into the window specified by WinId. If WinId exists, then the
process is placed into that memory window. If no window exists with
WinId, an unused window is allocated and associated with WinId. -c
specifies the creation of a window. If the window already exists and
-c is specified, the call fails. -j specifies the joining to an
existing window. If the window does not exist and -j is specified,
the call fails.
The -f option instructs the command to exec program regardless if the
setmemwindow is unable to change the process' window to the specified
WinId. The failure to create a specific window may be the effect of
the lack of available memory windows, the underlying kernel:
+ has not been configured with enough memory windows (exit
status [ENOMEM])
+ or was unable to allocate memory for a new window to meet this
request (exit status [ENOMEM])
Hewlett-Packard Company - 1 - HP-UX 11i Version 2: Sep 2004
setmemwindow(1M) setmemwindow(1M)
+ or the feature is not implemented (exit status [ENOSYS]).
Options [Toc] [Back]
-i WinId Specifies the desired memory window. WinId is a key to
the desired memory window. WinId is a user specified
value and should be one of the values contained in the
file /etc/services.window. Applications extract the user
key from /etc/services.window according to a unique string
contained in /etc/services.window, using the getmemwindow
command. (See getmemwindow(1M) and services.window(4).)
The kernel tries to locate an existing window with WinId.
If one is found, that window is used. If no window with
WinId is found, an unused entry is located and assigned to
WinId.
The value 0 for WinID is special. If specified, the
process/program is placed into the default global window
instead of a unique window with id WinId.
If WinID is unspecified, the process and its children will
run in a private memory window, and no other processes in
the system can attach to this memory window. This memory
window remains active until the process and its children
terminate.
-p pid | program [arg ...]
Change the memory window for process pid, or start program
in the specified memory window. If program has arguments
(arg ...), they must also be specified.
If -p is unspecified or the value of pid is 0, the calling
process has its window id changed, and program is exec'ed.
If a non-zero process pid is specified, only the window in
that process is changed, and program is ignored.
-c Create a window with id WinId and attach the specified
process to it. If WinId already exists the call fails.
-j Join an existing window with id WinId. The specified
process attaches to an existing memory window. If no
entry exists the call fails.
-n If program is exec'ed, the default behavior is to waitpid
(see the wait(2) manual page) for the process to
terminate. Specifying -n causes setmemwindow to exit
after fork'ing the child (that will exec program).
-f The default behavior for setmemwindow is to exit without
executing the user specified program if the memory window
Hewlett-Packard Company - 2 - HP-UX 11i Version 2: Sep 2004
setmemwindow(1M) setmemwindow(1M)
cannot be set. The failure to set the memory window may
be caused by:
+ The lack of enough memory windows in the system.
+ The memory windows feature is not implemented.
+ The request requires a new memory window be initialized
and the system was not able to allocate the memory to
do so.
+ A memory window with WinId could not be found in the
attempt to join a memory window.
+ A memory window with the WinId was found in the attempt
to create a memory window.
The -f option instructs setmemwindow to exec program
regardless if the desired memory window was set or not.
Obviously, using this option there is no guarantee program
has been attached to the desired memory window and it is
unclear in what memory window it is running. Using this
option is strongly discouraged.
-b Create a memory window where both memory window quadrants
use the same space id. For SHMEM_MAGIC executables this
generates two quadrants with the same space id.
Applications can use this to generate the appearance of
larger contiguous shared memory ranges with a maximum of 2
gigabytes. For example, an application that generates a
1 gigabyte shared memory segment has that segment placed
into the 2nd quadrant by default. If the application
creates another 1 gigabyte segment that segment is placed
in the 3rd quadrant. Both segments are contiguous
virtually, allowing the application to treat the virtual
range as if it were a contiguous 2 gigabyte segment.
This option only benefits SHMEM_MAGIC executables. They
are the only type of executable format able to place
shared objects in the 2nd quadrant.
-o Send the pid of the exec'ed program to the stdout. The
message sent out is: "setmemwindow:pid=dddd\n", where dddd
is the decimal value of the pid.
Application Usage [Toc] [Back]
Memory Windows helps alleviate the 1.75 gigabytes limitation on system
wide shared memory for 32-bit applications by allowing cooperating
applications to configure their own 1 gigabyte window of shared
resources.
Hewlett-Packard Company - 3 - HP-UX 11i Version 2: Sep 2004
setmemwindow(1M) setmemwindow(1M)
The definition of a memory window is only available for 32-bit
processes.
Note that memory windows allows the creation of more than 1.75
gigabytes of total system wide shared memory, but it does not extend
how much shared memory a single process can create. SHARED_MAGIC
executables are still limited to 1.75 gigabytes.
HP-UX ships memory windows disabled. To enable memory windows, the
kernel tunable parameter, max_mem_window, must be set to the desired
number. max_mem_window represents the number of memory windows beyond
the global default window. Setting max_mem_window to 2, for example,
would produce a total of three memory windows, the default global
window plus two user defined windows. Setting max_mem_window to 0
leaves only the default or global memory window.
There are two new commands and one file introduced by memory windows:
setmemwindow, getmemwindow, and /etc/services.window file.
The /etc/services.window file maps a memory window application to a
particular window id. Using this central file allows applications to
share memory windows, by using the same window id, as well as avoid
unintentional memory window collisions. See services.window(4) for
more information.
The getmemwindow command is used to extract the window id of a user
process from the /etc/services.window file. The setmemwindow command
starts a particular process in a memory window. A common usage of
these commands is to extract a memory window id with getmemwindow,
which is then passed to setmemwindow to start a process with the given
window id.
Processes must be in the same window to share data. Processes
wanting to share global data, such as shared memory or MAP_SHARED
memory mapped files, must make sure all processes are in the same
memory window. If processes in different memory windows wish to share
data reliably, the creator of the data must take steps to guarantee
the data is placed in a location accessible to all processes.
For more detailed information on memory windows, refer to the Memory
Windows in HP-UX 11.0 White Paper.
RETURN VALUE [Toc] [Back]
The returned exit value is 0 on success or a positive number on
failure.
If -n is not specified, the value returned is the exit status of the
executed program obtained from the waitpid(2) system call.
EXAMPLES [Toc] [Back]
#
Hewlett-Packard Company - 4 - HP-UX 11i Version 2: Sep 2004
setmemwindow(1M) setmemwindow(1M)
# Start the program "myprog" in a memory window extracted by the string
# "myapp".
#
WinId=$(getmemwindow myapp)
setmemwindow -i $WinId myprog arg1 arg2
#
# Start the program "myprog" in a newly created memory window
# extracted by the string "myapp".
#
WinId=$(getmemwindow myapp)
setmemwindow -c -i $WinId myprog arg1 arg2
#
# Start the program "myprog" in an existing memory window
# extracted by the string "myapp".
#
WinId=$(getmemwindow myapp)
setmemwindow -j -i $WinId myprog arg1 arg2
#
# Start the program "myprog" in a private memory window. Only
# "myprog" and its descendents can access the window.
#
setmemwindow myprog arg1 arg2
WARNINGS [Toc] [Back]
Programs using a memory window can access shared memory objects
created by other programs using the same window (depending upon
permissions). However, by default, programs using a memory window may
not be able to access shared memory objects created by programs using
other windows or those not using windows at all.
To enable access to a shared memory object across programs using
different windows, or between those using windows and those not using
windows, the program must specify special options when creating the
object. See shmget(2) and mmap(2) for details.
AUTHOR [Toc] [Back]
setmemwindow was developed by HP.
FILES [Toc] [Back]
/etc/services.window File containing applications' associated
window ids.
SEE ALSO [Toc] [Back]
getmemwindow(1M), services.window(4), Memory Windows in HP-UX 11.0
White Paper.
Hewlett-Packard Company - 5 - HP-UX 11i Version 2: Sep 2004 [ Back ] |
