msgctl(2) - NetBSD Manual Pages

MSGCTL(2)                 NetBSD System Calls Manual                 MSGCTL(2)


NAME

     msgctl -- message control operations


LIBRARY

     Standard C Library (libc, -lc)


SYNOPSIS

     #include <sys/msg.h>

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


DESCRIPTION

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

     Each message queue has a msqid_ds structure associated with it which con-
     tains the following members:

         struct ipc_perm msg_perm; /* msg queue permission bits */
         msgqnum_t msg_qnum;       /* # of msgs in the queue */
         msglen_t  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 msgid_ds structure is defined in
     <sys/ipc.h> and contains the following members:

         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 (lower 9 bits) */

     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 super-user, 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 super-user.  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 super-user 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, a value of 0 is returned.  Otherwise, -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 super-user, 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 was made to increase the value of
                        msg_qbytes through IPC_SET, but the caller is not the
                        super-user.

     [EACCES]           cmd 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)


STANDARDS

     The msgctl system call conforms to X/Open System Interfaces and Headers
     Issue 5 (``XSH5'').


HISTORY

     Message queues appeared in the first release of AT&T System V UNIX.

NetBSD 5.0                      August 25, 1999                     NetBSD 5.0