OBSOLETE Cygutils - Utilities for Cygwin

UP
Obsolete CygUtils Home
Obsolete V1.1 Home

cygipc

News

Notes:

Download:

README

# $Id: README,v 1.15 2001/09/19 03:35:07 cwilson Exp $

CygIPC provides shared memory, semaphores, and message support
for cygwin.  It provides the following functions:
   msgget      semget      shmget
   msgrcv      semop       shmat
   msgsnd      semctl      shmdt
   msgctl                  shmctl

The following functions are non-portable, but may help
in debugging your code.
   cygipc_set_err_handler, cygipc_get_err_handler
   cygipc_set_debug, cygipc_get_debug
   cygipc_tracing_enabled 

=========================================
Known Issues:

1) If shutting down and restarting ipc-daemon 
   under DIFFERENT users, you must "clean out"
   the IPC files in /tmp.  These include:
      /tmp/MultiFileMsg
      /tmp/MultiFileSem
      /tmp/MultiFileShm
      /tmp/cygipc*

=========================================

- ipc-daemon:

  *** Windows 9x/ME ****
  Under W9X ipc-daemon can be started from a shell prompt or 
  from the autostart folder, or from the Explorer.  However,
  if you start ipc-daemon from a command.com prompt you will 
  not see any of the debugging, help, or error output.  This
  unfortunately includes messages such as 
    "ipc-daemon: Installing service `ipc-daemon' failed"
  Oops.

  The workaround is to call ipc-daemon as shown below, when
  you must call it from a command.com/cmd.exe box:
  
    ipc-daemon [options] 2>&1 | cat

  or to call it only from a bash prompt, not from a `naked'
  command.com prompt.

  I realize this is an awkward restriction, but it appears that 
  the alternative is to compile ipc-daemon without -mwindows 
  (e.g. edit the Makefile and change the definition of the 
  IPCDAEMON_SPECIAL macro).  However, if you do this, you'll 
  end up with an ugly, empty command.com box every time you 
  start ipc-daemon -- even if you start it from a shortcut in 
  your Startup folder.  Worse, if you ever close that ugly,
  empty dosbox, ipc-daemon will die.  So it seems that the 
  awkward behavior above is a better compromise.  

  Do not under any circumstances call ipc-daemon with the
  '--service' option; it will NOT do what you think.  That
  option is intended for use ONLY in Windows NT/2K and
  even then, ONLY when ipc-daemon is started by the
  service manager.

  *** Windows NT/2K ***
  Under NT/W2K ipc-daemon should be started from service 
  manager. It must not be started via SRVANY but it has 
  two new options to install or remove it as service 
  (but these commands can only be run as Administrator):

        ipc-daemon --install-as-service
        ipc-daemon --remove-as-service

  When you already have an older version of ipc-daemon installed,
  please remove the service before installing the new one.  Note
  that when running `ipc-deamon --install-as-service' it WILL
  honor other options; for instance:

        ipc-daemon --install-as-service --debug

  will install the ipc-daemon as a service with appropriate 
  registry settings so that the daemon will always start using
  the `--debug' option.  Ditto the `--tight-security' option: see
  SECURITY section for more info.

  Remember, if you are calling ipc-daemon from a `naked'
  dosbox, you'll need to use the `2>&1 | cat' workaround in order
  to see the output of the above commands -- see the W9X discussion
  above.

  If you don't start ipc-daemon as service under LocalSystem but under
  another account, you have to care that that account has several
  user rights set in the user manager resp. local/domain security
  policy mmc snap in:
        "Logon as a service" (currently required)
        "Act as part of the operating system" (not necessary yet...)
        "Replace process level token" (not necessary yet...)
        "Increase quotas" (not necessary yet...)
  Note that administrators do not have all that user rights set
  by default!

  I created a user called "services" on my machine, to which
  I added these rights.  Then, I start sshd, inetd, and ipc-daemon
  under that account. 

  *** USER ACCOUNT requirements ***
  Note that the user account under which ipc-daemon is started
  must have a full configuration -- that is,

  - The environment variable CYGWIN must be set either in the
    system environment or you can set CYGWIN thru the registry:
    Under the key HKLM\Software\Cygnus Solutions\Cygwin\Program Options
    create a key of type REG_SZ (String) named like the full DOS path
    to the application, eg. "C:\cygwin\usr\local\bin\ipc-daemon.exe" 
    and with the value equal to the preferred CYGWIN settings, 
    eg "binmode tty ntsec".

  - The system environment variable PATH (or PATH variable for the 
    user under which ipc-daemon is started)  must contain the path
    to the directory which contains the cygwin1.dll.

  - Only the system mount table and the user mount table for the
    user under which ipc-daemon is running are valid! 

  *** LocalSystem requirements ***
  For all applications started via NT/W2K service manager under
  LocalSystem account, the following restrictions apply:

  - The environment variable CYGWIN must be set either in
    the system environment or via the registry (see USER
    ACCOUNT requirements above)

  - The system environment variable PATH must contain the path
    to the directory which contains the cygwin1.dll

  - Only the system mount table is valid!

  After you have installed ipc-daemon it will be started 
  automatically on reboot. Manually starting and stopping 
  is possible via

        net start ipc-daemon
        net stop ipc-daemon

  You can also run ipc-daemon on a temporary basis by starting
  it directly:

        ipc-daemon &   /* or ipc-daemon -d & */

  but this is not recommended except for debugging purposes.

  *** SECURITY CONCERNS ***
  The following discussion applies only to WinNT/2K; Win9x has 
  no security to speak of.

  In its default configuration when run as a service, ipc-daemon
  has zero security.  Any client can access, create, delete, or 
  read any shared msg, memory segment, or semaphore.

  Eventually we hope to implement a more realistic security model.
  However, for now, you have two choices: run ipc-daemon in its
  default `wide-open' zero-security mode, or restrict ipc usage to
  a single user account.  If you want to restrict ipc usage to a
  single user, you should run the ipc-daemon under that user,
  either manually or as a service (not under the LocalSystem user).

  You should also add the '-t' option (alt: --tight-security) 
  to the command with which you start ipc-daemon.

  So, if you want to start ipc-daemon manually, you would
  execute the following command from a DOS or BASH box:

        ipc-daemon --tight-security [--debug]

  If you want to run ipc-daemon as a service under a specific 
  user, it's a bit more complicated.  Follow these steps:

   1) install the service:
          ipc-daemon --install-as-service --tight-security
      Note that if ipc-daemon is already installed as a service,
      you should --remove-as-service before re-installing.

   2) Use the control panel to edit the service's properties:
    a) change the user from LocalSystem to the desired account
    b) type the appropriate password

  For the adventurous: you can use regedit to edit the following 
  key and change the service's startup parameters....
  HKLM\SYSTEM\CurrentControlSet\Services\ipc-daemon\Parameters
    Debug:
      0 (no debug)
      1 (do record debug messages to syslog)
    TightSecurity:
      0 (zero security -- wide open)
      1 (single-user)

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

Where to find this package:
  http://cygutils.netpedia.net/V1.1/cygipc/

Requirements:
  gcc-2.95.2-7 or later
   -- if you use an earlier release of gcc, you'll need to edit
      the Makefile and remove '-mwin32' from the CFLAGS_i386 macro
  cygwin-1.1.4 or later
  binutils-20000722-1 or later

Direct Dependencies:
  popt-1.6.1-1 or newer 

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

To link this library with your projects:
  #1) include one or more of:
      ( sys/msg.h, sys/sem.h, and sys/shm.h )
  #2) for debugging and error redirection, also
      include sys/ipctrace.h.  See NOTES below.
  #3) link with the static library using '-lcygipc'

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

To build the library for cygwin:

unpack cygipc-1.XX-X-src.tar.gz
cd cygipc-1.XX
make
make install

There are no automated tests, but you can use 'ipctest.exe' 
to manually verify operation of the library.  To do this:

  #1) You may need to delete manually some old files in your 
      /tmp directory, such as /tmp/MultiFileSem, /tmp/MultiFileShm, 
      and /tmp/MultiFileMsg
  #2) start './ipc-daemon.exe &'
  #3) run './ipctest.exe [options]'

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

Files included in the binary distro

  /lib/libcygipc.a
  /bin/ipc-daemon.exe
  /bin/ipck
  /bin/ipcrm.exe
  /bin/ipcs.exe
  /bin/ipctest.exe
  /doc/cygipc-x.xx/
  /doc/cygipc-x.xx/README
  /doc/cygipc-x.xx/README.old
  /doc/cygipc-x.xx/COPYING
  /doc/cygipc-x.xx/NEWS
  /doc/cygipc-x.xx/USAGE
  /doc/cygipc-x.xx/TODO
  /doc/cygipc-x.xx/index.html
  /doc/cygipc-x.xx/node*.html
  /doc/cygipc-x.xx/*.gif
  /include/sys/ipc.h
  /include/sys/ipctrace.h
  /include/sys/msg.h
  /include/sys/sem.h
  /include/sys/shm.h

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

Port Notes:

1.0.9:
-------------------------------------------------

Programming with cygipc:  The library has a built in
  mechanism for redirecting error messages (and TRACE
  messages if the library was compiled with -DTRACE).
  Ordinarily, library-internal error messages are 
  printed to stderr, but this can be changed by declaring
  a function that matches the following signature:
    #include 
    int my_err_handler(FILE *stream, int severity, const char *fmt, ...);
  then, call
    cygipc_set_err_handler(my_err_handler);

  Also provided in ipctrace.h are:
    err_handlerP typedef, and the 
    err_handlerP cygipc_get_err_handler(void);
  function.
  
  severity usually indicates the message LOG level, such
  as LOG_ERR, LOG_DEBUG, etc.  See 

  For an example of handling library error messages, see
  the source code for ipctest.c.

Tracing:  When the library is compiled with -DTRACE, it 
  outputs tracing messages (via err_handler) to stderr.
  You can turn this off by calling:
    cygipc_set_debug(0);
  and get current debug status by calling:
    int cygipc_get_debug(void);
  Also, you can determine whether the library was compiled
  with -DTRACE by calling:
    int cygipc_tracing_enabled(void);
  Currently, get_debug and set_debug exist, but have
  no effect unless the libary was compiled with -DTRACE.

Tracing and library error messages in ipc-daemon:
  Note that the ONLY functions in the library that ipc-daemon
  itself actually calls are:
    name_mangle()
    cygipc_set_debug(), cygipc_get_debug()
    cygipc_set_err_handler()
  Given the current state of libcygipc, AND the fact that
  ipc-daemon never calls any of the "important" library 
  functions (like semctl, etc) -- the debugging stuff
  has little practical effect in redirecting *library*
  error messages incurred by ipc-daemon.  (The only function 
  capable of producing an error/trace message is 
  name_mangle() -- and it doesn't call any of the tracing 
  or printing functions)!

  However, the err_message redirect and debug setting stuff
  is here "just in case" ipc-daemon ever calls the "important"
  functions in the library in future releases.

GENERAL:
--------------------------------------------------

This package was originally located here:
   http://www.multione.capgemini.fr/tools/pack_ipc/
but the server has been inaccessible since early December 99.
CygIPC was originally written by Philippe CHAPUY and Ludovic LANGE,
and those authors still own the copyright.  However, since 
repeated efforts to contact them by myself and others has failed, 
I officially forked the code at v1.03 and maintain this version.

I found a mirror of the original code here:
   http://dods.jpl.nasa.gov/WinPort/portEnvSetup.html
   ftp://podaac.jpl.nasa.gov/pub/users/rmorris/DodsWin32Port/cygwinB20IPC.tar.gz
but it was compiled for B20.1 and needed some fixups to compile
with newew Cygwin kernels.

Compilation options:

  Edit the makefile and add the following to CONF_FLAGS:
  
  -DSHMAT_LINUX will result in a shmat function with this signature:
    int shmat(int shmid, char *shmaddr, int shmflg, char **adr);
  otherwise, shmat has this signature:
    char * shmat(int shmid, char *shmaddr, int shmflg);
  I did NOT use SHMAT_LINUX.

  -DTRACE will build a library with execution traces to stderr (this does
    *not* use the cygwin strace function, but looks a lot like it).
  I did NOT use TRACE.

Makefile targets (typical):
  make all
  make clean
  make realclean
  make install

Cygwin port maintained by: Charles Wilson cwilson@ece.gatech.edu

Obsolete V1.1 Home

Obsolete CygUtils Home

Last modified: Mon Nov 26 22:58:20 EST 2001 EOF