*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->OpenBSD man pages -> msgctl (2)              



NAME    [Toc]    [Back]

     msgctl - message control operations

SYNOPSIS    [Toc]    [Back]

     #include <sys/types.h>
     #include <sys/ipc.h>
     #include <sys/msg.h>

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

DESCRIPTION    [Toc]    [Back]

     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 shmid_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

     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,
                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 executed
  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
                <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
                values in the data structure associated with  the
queue can do

     The permission to read from or write to a message queue (see
     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 effective
     GID can match either msg_perm.cgid or msg_perm.gid.

RETURN VALUES    [Toc]    [Back]

     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    [Toc]    [Back]

     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
                   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    [Toc]    [Back]

     msgget(2), msgrcv(2), msgsnd(2)

HISTORY    [Toc]    [Back]

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

OpenBSD      3.6                          August     17,     1995
[ Back ]
 Similar pages
Name OS Title
msgctl Tru64 Perform message control operations
msgop Linux message operations
msgop IRIX message operations
msgsnd HP-UX message operations
msgrcv HP-UX message operations
msgop HP-UX message operations
BIO_get_info_callback Tru64 BIO control operations
BIO_flush Tru64 BIO control operations
BIO_get_close Tru64 BIO control operations
BIO_set_info_callback Tru64 BIO control operations
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service