unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OpenBSD-5.7)
Page:
Section:
Apropos / Subsearch:
optional field

MSGCTL(2)                   BSD System Calls Manual                  MSGCTL(2)

NAME
     msgctl -- message control operations

SYNOPSIS
     #include <&lt;sys/msg.h>&gt;

     int
     msgctl(int msqid, int cmd, struct msqid_ds *buf);

DESCRIPTION
     The msgctl() system call performs some control operations on the message
     queue specified by msqid.

     Each message queue has a data structure associated with it, parts of
     which may be altered by msgctl() and parts of which determine the actions
     of msgctl().  The data structure is defined in <sys/msg.h> and contains
     (amongst others) the following members:

     struct msqid_ds {
             struct ipc_perm msg_perm;       /* msg queue permission bits */
             u_long          msg_cbytes;     /* # of bytes in use on the queue */
             u_long          msg_qnum;       /* # of msgs in the queue */
             u_long          msg_qbytes;     /* max # of bytes on the queue */
             pid_t           msg_lspid;      /* pid of last msgsnd() */
             pid_t           msg_lrpid;      /* pid of last msgrcv() */
             time_t          msg_stime;      /* time of last msgsnd() */
             time_t          msg_rtime;      /* time of last msgrcv() */
             time_t          msg_ctime;      /* time of last msgctl() */
     };

     The ipc_perm structure used inside the msqid_ds structure is defined in
     <sys/ipc.h> and looks like this:

     struct ipc_perm {
             uid_t   cuid;   /* creator user id */
             gid_t   cgid;   /* creator group id */
             uid_t   uid;    /* user id */
             gid_t   gid;    /* group id */
             mode_t  mode;   /* permission (9 bits, see chmod(2)) */
             u_short seq;    /* sequence # (to generate unique id) */
             key_t   key;    /* user specified msg/sem/shm key */
     };

     The operation to be performed by msgctl() is specified in cmd and is one
     of:

     IPC_STAT   Gather information about the message queue and place it in the
                structure pointed to by buf.

     IPC_SET    Set the value of the msg_perm.uid, msg_perm.gid, msg_perm.mode
                and msg_qbytes fields in the structure associated with msqid.
                The values are taken from the corresponding fields in the
                structure pointed to by buf.  This operation can only be exe-
                cuted by the superuser, or a process that has an effective
                user ID equal to either msg_perm.cuid or msg_perm.uid in the
                data structure associated with the message queue.  The value
                of msg_qbytes can only be increased by the superuser.  Values
                for msg_qbytes that exceed the system limit (MSGMNB from
                <sys/msg.h>) are silently truncated to that limit.

     IPC_RMID   Remove the message queue specified by msqid and destroy the
                data associated with it.  Only the superuser or a process with
                an effective UID equal to the msg_perm.cuid or msg_perm.uid
                values in the data structure associated with the queue can do
                this.

     The permission to read from or write to a message queue (see msgsnd(2)
     and msgrcv(2)) is determined by the msg_perm.mode field in the same way
     as is done with files (see chmod(2)), but the effective UID can match
     either the msg_perm.cuid field or the msg_perm.uid field, and the effec-
     tive GID can match either msg_perm.cgid or msg_perm.gid.

RETURN VALUES
     Upon successful completion, the value 0 is returned; otherwise the
     value -1 is returned and the global variable errno is set to indicate the
     error.

ERRORS
     msgctl() will fail if:

     [EPERM]            cmd is equal to IPC_SET or IPC_RMID and the caller is
                        not the superuser, nor does the effective UID match
                        either the msg_perm.uid or msg_perm.cuid fields of the
                        data structure associated with the message queue.

                        An attempt is made to increase the value of msg_qbytes
                        through IPC_SET but the caller is not the superuser.

     [EACCES]           The command is IPC_STAT and the caller has no read
                        permission for this message queue.

     [EINVAL]           msqid is not a valid message queue identifier.

                        cmd is not a valid command.

     [EFAULT]           buf specifies an invalid address.

SEE ALSO
     msgget(2), msgrcv(2), msgsnd(2)

HISTORY
     Message queues appeared in AT&T System V Release 1 UNIX.

BSD                             April 28, 2017                             BSD