Re: OS X shared memory documentation

Great.  I have applied the following documentation patch for CVS HEAD
and 8.1.X.

It seems you are saying that shmmax and shmall must be multiples of 4k,
and I added that to the docs.  It previously only mentioned shmmax in
that regard.

---------------------------------------------------------------------------

Chris Campbell wrote:
> The definitive answer can be found in the source code for the Darwin
> kernel, xnu (links are below):
>
> 1. The shmmax, shmmin, shmmni, shmseg, and shmall settings cannot be
> changed after the shared memory system is initialized
>
> 2. The shared memory system is initialized immediately after all 5
> settings have been configured
>
> 3. The shmall setting must be a multiple of the page size (on both
> 10.3 and 10.4)
>
> Here are excerpts from the sysctl_shminfo() function found in
> sysv_shm.c:
>
> [1]
>      /* Set the values only if shared memory is not initialised */
>      if (!shm_inited) {
>          if ((error = SYSCTL_IN(req, arg1, sizeof(user_ssize_t)))
>              != 0) {
>              sysctl_shminfo_ret = error;
>              goto sysctl_shminfo_out;
>          }
>
> [2]
>          /* Initialize only when all values are set */
>          if ((shminfo.shmmax != (user_ssize_t)-1) &&
>              (shminfo.shmmin != (user_ssize_t)-1) &&
>              (shminfo.shmmni != (user_ssize_t)-1) &&
>              (shminfo.shmseg != (user_ssize_t)-1) &&
>              (shminfo.shmall != (user_ssize_t)-1)) {
>                  shminit(NULL);
>          }
>
>
> [3]
> (10.3)
>          if (arg1 == &shminfo.shmmax) {
>              if (shminfo.shmmax & PAGE_MASK) {
>                  shminfo.shmmax = -1;
>                  return(EINVAL);
>              }
>          }
>
> (10.4)
>          if (arg1 == &shminfo.shmmax) {
>              if (shminfo.shmmax & PAGE_MASK_64) {
>                  shminfo.shmmax = -1;
>                  return(EINVAL);
>              }
>          }
>
> PAGE_MASK is "(PAGE_SIZE - 1)", and PAGE_MASK_64 is simply "(unsigned
> long long)PAGE_MASK"
>
>
> /etc/rc contains commands to set all 5 of the parameters. In 10.3.9
> and later, you can place your own customized settings inside /etc/
> sysctl.conf that will be executed before /etc/rc's commands. But if
> you don't set them all, the shared memory system isn't initialized,
> and /etc/rc will overwrite them.
>
> Does that make sense?
>
> In a nutshell, if you want to customize the shared memory settings,
> you must:
>
> (On 10.3.9 and later)
> Set ALL 5 settings inside /etc/sysctl.conf, and make sure that shmmax
> is a multiple of the page size (4096?). The page size is a runtime
> variable that's set by kernel bootstrap mechanisms calling
> vm_set_page_size() (I haven't tracked those down yet).
>
> (On earlier systems)
> Modify the desired settings inside /etc/rc, and be aware that OS
> updates will overwrite your changes. If you upgrade to 10.3.9,
> migrate to using /etc/sysctl.conf.
>
> In my own OS X products that use a PostgreSQL server, I install an /
> etc/sysctl.conf file on all servers. If installing on anything
> earlier than 10.3, my installer modifies /etc/rc. That way, when the
> customer upgrades their server to 10.3.9 and the /etc/rc file is
> overwritten, the /etc/sysctl.conf file is already in place.
>
> Thanks!
>
> - Chris
>
>
> Referenced source code:
>
> Mac OS X 10.4.4:
>     http://www.opensource.apple.com/darwinsource/10.4.4.ppc/
> xnu-792.6.56/bsd/kern/sysv_shm.c
>
> Mac OS X 10.3.9:
>     http://www.opensource.apple.com/darwinsource/10.3.9/xnu-517.12.7/
> bsd/kern/sysv_shm.c
>
> Mac OS X 10.3:
>     http://www.opensource.apple.com/darwinsource/10.3/xnu-517/bsd/
> kern/sysv_shm.c
>

--
  Bruce Momjian   http://candle.pha.pa.us
  SRA OSS, Inc.   http://www.sraoss.com

  + If your life is a hard drive, Christ can be your backup. +
Index: doc/src/sgml/runtime.sgml
===================================================================
RCS file: /cvsroot/pgsql/doc/src/sgml/runtime.sgml,v
retrieving revision 1.361
diff -c -c -r1.361 runtime.sgml
*** doc/src/sgml/runtime.sgml    5 Jan 2006 03:01:33 -0000    1.361
--- doc/src/sgml/runtime.sgml    2 Mar 2006 20:28:06 -0000
***************
*** 886,904 ****
          changes take effect.
         </para>

! <!--
! It might appear that we could recommend putting sysctl settings into
! /etc/sysctl.conf so that they aren't destroyed by OS version updates.
! This does not work as of OS X 10.4.2, however, because /etc/rc
! promptly overrides whatever SHM settings are read from sysctl.conf :-(
! Perhaps someday we can recommend this ...
! -->

         <para>
!         <varname>SHMALL</> is measured in 4KB pages on this platform.
!         Also note that some releases of OS X will reject attempts to
!         set <varname>SHMMAX</> to a value that isn't an exact multiple
!         of 4096.
         </para>
        </listitem>
       </varlistentry>
--- 886,904 ----
          changes take effect.
         </para>

!        <para>
!         In OS X 10.3.9 and later, the file <filename>/etc/sysctl.conf</>
!         allows shared memory setting to be saved across operating system
!         upgrades, and is the recommended method for setting these
!         parameters. When using this file, all five shared memory values
!         must be set or the changes will be ignored.
!        </para>

         <para>
!         <varname>SHMALL</> is measured in 4KB pages on this platform,
!         and recent releases of OS X reject attempts to set
!         <varname>SHMALL</> and <varname>SHMMAX</> to a value
!         that isn't an exact multiple of 4096.
         </para>
        </listitem>
       </varlistentry>