unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (HP-UX-11.11)
Page:
Section:
Apropos / Subsearch:
optional field



 setmemwindow(1M)					    setmemwindow(1M)




 NAME
      setmemwindow - changes the window id of a running program or starts a
      program in a particular memory window

 SYNOPSIS
      setmemwindow [ -cjnfbov ] [ -i WinId ]
	   -p pid | program [ arg ...]

 DESCRIPTION
      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 the
      feature is not implemented (exit status ENOSYS).

    Options
      -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



 Hewlett-Packard Company	    - 1 -   HP-UX Release 11i: November 2000






 setmemwindow(1M)					    setmemwindow(1M)




		  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
		  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, a
		  memory window with WinId could not be found in the attempt
		  to join a memory window, or a memory window with the WinId
		  was found in the attempt to create a memory window.  The



 Hewlett-Packard Company	    - 2 -   HP-UX Release 11i: November 2000






 setmemwindow(1M)					    setmemwindow(1M)




		  -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
      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.

      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.





 Hewlett-Packard Company	    - 3 -   HP-UX Release 11i: November 2000






 setmemwindow(1M)					    setmemwindow(1M)




      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 11.0
      Memory Window White Paper.

 RETURN VALUE
      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
      #
      # 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".



 Hewlett-Packard Company	    - 4 -   HP-UX Release 11i: November 2000






 setmemwindow(1M)					    setmemwindow(1M)




      #
      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

 AUTHOR
      setmemwindow was developed by HP.

 FILES
      /etc/services.window	    File containing applications' associated
				    window ids.

 SEE ALSO
      getmemwindow(1M), services.window(4), 11.0 Memory Windows White Paper.



































 Hewlett-Packard Company	    - 5 -   HP-UX Release 11i: November 2000