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