{"id":7509,"library":"posix-ipc","title":"POSIX IPC for Python","description":"posix-ipc is a Python module, implemented in C, that provides access to POSIX inter-process communication primitives: semaphores, shared memory, and message queues. It enables Python applications to communicate with non-Python programs on systems supporting POSIX Realtime Extensions (POSIX 1003.1b-1993), including most Unix-like platforms and Windows via Cygwin or WSL. The current version is 1.3.2, with releases typically tied to bug fixes and modernization efforts rather than a strict cadence.","status":"active","version":"1.3.2","language":"en","source_language":"en","source_url":"https://github.com/osvenskan/posix_ipc/","tags":["IPC","POSIX","semaphore","shared memory","message queue","inter-process communication"],"install":[{"cmd":"pip install posix-ipc","lang":"bash","label":"Install from PyPI"}],"dependencies":[],"imports":[{"symbol":"Semaphore","correct":"from posix_ipc import Semaphore"},{"symbol":"SharedMemory","correct":"from posix_ipc import SharedMemory"},{"symbol":"MessageQueue","correct":"from posix_ipc import MessageQueue"},{"symbol":"O_CREAT","correct":"from posix_ipc import O_CREAT"},{"symbol":"O_EXCL","correct":"from posix_ipc import O_EXCL"}],"quickstart":{"code":"import posix_ipc\nimport os\n\n# Semaphore Example\nSEM_NAME = '/my_semaphore'\ntry:\n    sem = posix_ipc.Semaphore(SEM_NAME, posix_ipc.O_CREAT, initial_value=1)\n    print(f\"Semaphore '{SEM_NAME}' created/opened. Value: {sem.value}\")\n    sem.acquire()\n    print(f\"Semaphore acquired. Value: {sem.value}\")\n    sem.release()\n    print(f\"Semaphore released. Value: {sem.value}\")\nfinally:\n    if 'sem' in locals() and sem.name == SEM_NAME: # Ensure it's our semaphore and still valid\n        sem.close()\n        sem.unlink()\n        print(f\"Semaphore '{SEM_NAME}' closed and unlinked.\")\n\n# Shared Memory Example\nSHM_NAME = '/my_shared_memory'\nSIZE = 128\ntry:\n    shm = posix_ipc.SharedMemory(SHM_NAME, posix_ipc.O_CREAT, size=SIZE)\n    print(f\"Shared Memory '{SHM_NAME}' created/opened with size {SIZE}.\")\n    # In a real app, you'd mmap this and write/read bytes\n    # e.g., memory_map = mmap.mmap(shm.fd, shm.size)\n    # memory_map.write(b'Hello from shared memory!')\nfinally:\n    if 'shm' in locals() and shm.name == SHM_NAME:\n        shm.close_fd() # Close the file descriptor\n        shm.unlink()\n        print(f\"Shared Memory '{SHM_NAME}' unlinked.\")\n\n# Message Queue Example (Note: Message queues are not supported on macOS by posix-ipc)\n# This example will likely fail on macOS due to OS limitations.\n# For a runnable example, execute on Linux/WSL.\nMQ_NAME = '/my_message_queue'\nif os.uname().sysname != 'Darwin': # Check if not macOS\n    try:\n        mq = posix_ipc.MessageQueue(MQ_NAME, posix_ipc.O_CREAT, max_messages=10, max_message_size=64)\n        print(f\"Message Queue '{MQ_NAME}' created/opened.\")\n        message = b\"Hello from message queue!\"\n        mq.send(message)\n        print(f\"Sent: {message.decode()}\")\n        received_message, _ = mq.receive()\n        print(f\"Received: {received_message.decode()}\")\n    except posix_ipc.PermissionsError as e:\n        print(f\"Caught PermissionsError for MessageQueue: {e}. This might happen if queue exists with different permissions.\")\n    except posix_ipc.ExistentialError as e:\n        print(f\"Caught ExistentialError for MessageQueue: {e}. This might happen if queue exists with incompatible settings.\")\n    except Exception as e:\n        print(f\"An unexpected error occurred with MessageQueue: {e}\")\n    finally:\n        if 'mq' in locals() and mq.name == MQ_NAME:\n            try:\n                mq.close()\n                mq.unlink()\n                print(f\"Message Queue '{MQ_NAME}' closed and unlinked.\")\n            except Exception as e:\n                print(f\"Error during MessageQueue cleanup: {e}\")\nelse:\n    print(\"MessageQueue example skipped: Not supported on macOS by posix-ipc.\")\n","lang":"python","description":"This quickstart demonstrates the basic usage of POSIX semaphores, shared memory, and message queues. It shows how to create, use, and explicitly clean up these IPC objects. Note the platform-specific behavior for message queues. For shared memory, only creation and unlinking are shown; actual data exchange requires `mmap`."},"warnings":[{"fix":"Migrate away from using `posix_ipc.PAGE_SIZE` and `posix_ipc.SEMAPHORE_VALUE_MAX`. Consult system `os.sysconf` or `mmap` documentation for alternatives if needed.","message":"The module constants `PAGE_SIZE` and `SEMAPHORE_VALUE_MAX` have been deprecated as of version 1.3.0 and will be removed in a future release. Avoid using them in new code.","severity":"deprecated","affected_versions":">=1.3.0"},{"fix":"Always call `obj.unlink()` on IPC objects when they are no longer needed. Use `try...finally` blocks to ensure unlinking, even if errors occur during operation. Consider using `O_EXCL` with `O_CREAT` for exclusive creation to avoid conflicts with existing objects.","message":"POSIX IPC objects (semaphores, shared memory, message queues) are persistent and survive program termination. Failing to explicitly unlink them can lead to resource leaks or unexpected behavior from stale objects.","severity":"gotcha","affected_versions":"All"},{"fix":"Understand that `close()` is for releasing a process's reference, while `unlink()` removes the system-wide object. Call `unlink()` when the object is globally no longer needed by any process. Avoid using a `posix_ipc` object after calling `close()` on it, unless for `unlink()` or `name` access.","message":"The `posix_ipc.close()` method sets the internal C pointer to NULL but does not unlink the IPC object from the system. Attempting to acquire or release a semaphore after `close()` but before `unlink()` will raise an `ExistentialError`.","severity":"gotcha","affected_versions":"All"},{"fix":"Be aware of platform limitations. Test IPC functionality on the target OS. For macOS, avoid message queues entirely when using `posix-ipc`. For cross-platform Python IPC, consider `multiprocessing` or `multiprocessing.shared_memory`.","message":"Message queues and certain semaphore functions (`sem_getvalue()`, `sem_timedwait()`) are not supported on macOS by the underlying OS, and thus `posix-ipc` cannot provide them. Windows requires Cygwin or WSL for POSIX IPC support.","severity":"gotcha","affected_versions":"All"},{"fix":"If all communicating processes are Python, evaluate `multiprocessing` first for simpler and more Pythonic IPC patterns.","message":"For inter-process communication *between Python programs*, it is generally recommended to use Python's built-in `multiprocessing` module (or `multiprocessing.shared_memory` for shared memory) instead of `posix-ipc`. `posix-ipc` is designed primarily for IPC between Python and *non-Python* applications.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure the semaphore object is valid and has not been closed or unlinked. If opening, use `posix_ipc.O_CREAT` to create it if it doesn't exist, or `posix_ipc.O_CREAT | posix_ipc.O_EXCL` for exclusive creation.","cause":"Attempted to acquire or release a semaphore that has been closed (via `sem.close()`) or unlinked, or to open a semaphore with default flags when it doesn't exist.","error":"posix_ipc.ExistentialError: semaphore doesn't exist"},{"fix":"Check the `mode` parameter when creating IPC objects (e.g., `0o600` for owner read/write). Ensure the process has sufficient user/group permissions for the IPC object. Verify that `umask` settings are not overly restrictive.","cause":"The current process lacks the necessary permissions to create, open, or operate on the IPC object (e.g., trying to write to a read-only shared memory segment, or opening an object with incompatible permissions).","error":"posix_ipc.PermissionsError: Operation not permitted"},{"fix":"Ensure the message queue is created with `posix_ipc.O_CREAT`. If on macOS, remember that message queues are not supported by `posix-ipc`. Verify that the queue name is consistent across processes and that permissions allow access.","cause":"Attempting to interact with a message queue that was either never created, has been unlinked, or the process does not have permission to access it, and `O_CREAT` was not used. Also common on unsupported platforms like macOS.","error":"posix_ipc.ExistentialError: Message queue doesn't exist"}]}