msgctl(2) - NetBSD Manual Pages

Command: Section: Arch: Collection:  
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 9.99 August 25, 1999 NetBSD 9.99
Powered by man-cgi (2020-09-24). Maintained for NetBSD by Kimmo Suominen. Based on man-cgi by Panagiotis Christias.