# Module `posix.sys.msg`

Sys V Message Queue Operations.

Where supported by the underlying system, functions to send and receive interprocess messages. If the module loads successfully, but there is no system support, then `posix.sys.msg.version` will be set, but the unsupported APIs wil be `nil`.

## Functions

msgctl (id, cmd) |
msgget (key[, flags=0]) | Get a message queue identifier
msgrcv (id, size, type[, flags=0]) | Receive message from a message queue
msgsnd (id, type, message[, flags=0]) | Send message to a message queue

## Tables

PosixMsqid | Message queue record.

## Constants

posix.sys.msg | Message constants.

## Functions

msgctl (id, cmd)

  ### Parameters:

  - id int message queue identifier returned by msgget
  - cmd int one of `IPC_STAT`, `IPC_SET` or `IPC_RMID`

  ### Returns:

  PosixMsqid table for id, with `IPC_STAT`, if successful

  ### Or

  non-nil, with `IPC_SET` or `IPC_RMID`, if successful

  ### Or

  1. nil otherwise
  2. string error message
  3. int errnum

  ### See also:

  msgctl(2)

  ### Usage:

      local sysvmsg = require 'posix.sys.msg'
      local msq = sysvmsg.msgget(sysvmsg.IPC_PRIVATE)
      local msqid, errmsg = sysvmsg.msgctl(msq, sysvmsg.IPC_STAT)
      assert(msqid, errmsg)
      assert(sysvmsg.msgctl(msq, sysvmsg.IPC_RMID))

msgget (key[, flags=0])
  Get a message queue identifier

  ### Parameters:

  - key int message queue id, or `IPC_PRIVATE` for a new queue
  - flags int bitwise OR of zero or more from `IPC_CREAT` and `IPC_EXCL`, and access permissions `S_IRUSR`, `S_IWUSR`, `S_IRGRP`, `S_IWGRP`, `S_IROTH` and `S_IWOTH` (from posix.sys.stat) (default 0)

  ### Returns:

  int message queue identifier, if successful

  ### Or

  1. nil
  2. string error message
  3. int errnum

  ### See also:

  msgget(2)
msgrcv (id, size, type[, flags=0])
  Receive message from a message queue

  ### Parameters:

  - id int message queue identifier returned by msgget
  - size int maximum message size
  - type int message type (optional, default - 0)
  - flags int bitwise OR of zero or more of `IPC_NOWAIT`, `MSG_EXCEPT` and `MSG_NOERROR` (default 0)

  ### Returns:

  1. int message type from msgsnd
  2. string message text, if successful

  ### Or

  1. nil
  2. string error message
  3. int errnum

  ### See also:

  msgrcv(2)
msgsnd (id, type, message[, flags=0])
  Send message to a message queue

  ### Parameters:

  - id int message queue identifier returned by msgget
  - type int arbitrary message type
  - message string content
  - flags int optionally `IPC_NOWAIT` (default 0)

  ### Returns:

  int `0`, if successful

  ### Or

  1. nil
  2. string error message
  3. int errnum

  ### See also:

  msgsnd(2)

## Tables

PosixMsqid
  Message queue record.

  ### Fields:

  - msg_qnum int number of messages on the queue
  - msg_qbytes int number of bytes allowed on the queue
  - msg_lspid int process id of last msgsnd
  - msg_lrpid int process id of last msgrcv
  - msg_stime int time of last msgsnd
  - msg_rtime int time of last msgrcv
  - msg_ctime int time of last change

## Constants

posix.sys.msg
  Message constants. Any constants not available in the underlying system will be `nil` valued.

  ### Fields:

  - IPC_STAT int return a Msqid table from msgctl
  - IPC_SET int set the Msqid fields from msgctl
  - IPC_RMID int remove a message queue with msgctl
  - IPC_CREAT int create entry if key does not exist
  - IPC_EXCL int fail if key exists
  - IPC_PRIVATE int private key
  - IPC_NOWAIT int error if request must wait
  - MSG_EXCEPT int read messages with differing type
  - MSG_NOERROR int truncate received message rather than erroring

  ### Usage:

      -- Print msg constants supported on this host.
      for name, value in pairs (require "posix.sys.msg") do
        if type (value) == "number" then
          print (name, value)
         end
      end

generated by LDoc 1.5.0 Last updated 2025-02-16 13:16:41