.Nm shmctl
.Nd shared memory control operations
.Sh SYNOPSIS
-.Fd #include <sys/types.h>
-.Fd #include <sys/ipc.h>
-.Fd #include <sys/msg.h>
+.Fd #include <sys/shm.h>
.Ft int
-.Fn shmctl "int shmid" "int cmd" "struct shmid_ds *buf"
+.Fo shmctl
+.Fa "int shmid"
+.Fa "int cmd"
+.Fa "struct shmid_ds *buf"
+.Fc
.Sh DESCRIPTION
The
.Fn shmctl
system call performs some control operations on the shared memory area
specified by
.Fa shmid .
-
Each shared memory segment has a data structure associated with it,
parts of which may be altered by
.Fn shmctl
and parts of which determine the actions of
.Fn shmctl .
-
This structure is defined as follows in
.Aq Pa sys/shm.h :
.Bd -literal
struct shmid_ds {
- struct ipc_perm shm_perm; /* operation permissions */
- int shm_segsz; /* size of segment in bytes */
- pid_t shm_lpid; /* pid of last shm op */
- pid_t shm_cpid; /* pid of creator */
- short shm_nattch; /* # of current attaches */
- time_t shm_atime; /* last shmat() time*/
- time_t shm_dtime; /* last shmdt() time */
- time_t shm_ctime; /* last change by shmctl() */
- void *shm_internal; /* sysv stupidity */
+ struct ipc_perm shm_perm; /* operation permissions */
+ int shm_segsz; /* size of segment in bytes */
+ pid_t shm_lpid; /* pid of last shm op */
+ pid_t shm_cpid; /* pid of creator */
+ short shm_nattch; /* # of current attaches */
+ time_t shm_atime; /* last shmat() time*/
+ time_t shm_dtime; /* last shmdt() time */
+ time_t shm_ctime; /* last change by shmctl() */
+ void *shm_internal; /* sysv stupidity */
};
.Ed
+.Pp
The
.Bf -literal
ipc_perm
and looks like this:
.Bd -literal
struct ipc_perm {
- ushort cuid; /* creator user id */
- ushort cgid; /* creator group id */
- ushort uid; /* user id */
- ushort gid; /* group id */
- ushort mode; /* r/w permission (see chmod(2)) */
- ushort seq; /* sequence # (to generate unique msg/sem/shm id) */
- key_t key; /* user specified msg/sem/shm key */
+ uid_t uid; /* Owner's user ID */
+ gid_t gid; /* Owner's group ID */
+ uid_t cuid; /* Creator's user ID */
+ gid_t cgid; /* Creator's group ID */
+ mode_t mode; /* r/w permission (see chmod(2)) */
+ unsigned short _seq; /* Reserved for internal use */
+ key_t _key; /* Reserved for internal use */
};
.Ed
-
+.Pp
The operation to be performed by
.Fn shmctl
is specified in
or
.Va shm_perm.uid
in the data structure associated with the shared memory segment.
-
.It Dv IPC_RMID
Remove the shared memory segment specified by
.Fa shmid
.Va shm_perm.uid
values in the data structure associated with the queue can do this.
.El
-
+.Pp
The read and write permissions on a shared memory identifier
are determined by the
.Va shm_perm.mode
or
.Va shm_perm.gid .
.Sh RETURN VALUES
-Upon successful completion, a value of 0 is returned. Otherwise, -1 is
-returned and the global variable
+Upon successful completion, a value of 0 is returned.
+Otherwise, -1 is returned and the global variable
.Va errno
is set to indicate the error.
.Sh ERRORS
.Fn shmctl
will fail if:
.Bl -tag -width Er
+.\" ===========
+.It Bq Er EACCES
+The command is IPC_STAT
+and the caller has no read permission for this shared memory segment.
+.\" ===========
+.It Bq Er EFAULT
+.Fa buf
+specifies an invalid address.
+.\" ===========
+.It Bq Er EINVAL
+.Fa shmid
+is not a valid shared memory segment identifier.
+.Va cmd
+is not a valid command.
+.\" ===========
.It Bq Er EPERM
.Fa 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
+is equal to IPC_SET or IPC_RMID and the caller is not the super-user,\
+nor does the effective uid match either the
.Va shm_perm.uid
or
.Va shm_perm.cuid
fields of the data structure associated with the shared memory segment.
-
An attempt is made to increase the value of
.Va shm_qbytes
through IPC_SET
but the caller is not the super-user.
-.It Bq Er EACCESS
-The command is IPC_STAT
-and the caller has no read permission for this shared memory segment.
-.It Bq Er EINVAL
-.Fa shmid
-is not a valid shared memory segment identifier.
-
-.Va cmd
-is not a valid command.
-.It Bq Er EFAULT
-.Fa buf
-specifies an invalid address.
.El
+.Sh LEGACY SYNOPSIS
+.Fd #include <sys/types.h>
+.Fd #include <sys/ipc.h>
+.Fd #include <sys/shm.h>
+.Pp
+All of these include files are necessary.
+.Sh LEGACY DESCRIPTION
+The
+.Bf -literal
+ipc_perm
+.Ef
+structure used inside the
+.Bf -literal
+shmid_ds
+.Ef
+structure, as defined in
+.Aq Pa sys/ipc.h ,
+looks like this:
+.Bd -literal
+struct ipc_perm {
+ __uint16_t cuid; /* Creator's user id */
+ __uint16_t cgid; /* Creator's group id */
+ __uint16_t uid; /* Owner's user id */
+ __uint16_t gid; /* Owner's group id */
+ mode_t mode; /* r/w permission (see chmod(2)) */
+ __uint16_t seq; /* Reserved for internal use */
+ key_t key; /* Reserved for internal use */
+};
+.Ed
+.Pp
+This structure is maintained for binary backward compatibility
+with previous versions of the interface.
+New code should not use this interface,
+because ID values may be truncated.
+.Pp
+Specifically,
+LEGACY mode limits the allowable uid/gid ranges to 0-32767.
+If the user has a UID that is out of this range (e.g., "nobody"),
+software using the LEGACY API will not behave as expected.
.Sh SEE ALSO
.Xr shmat 2 ,
.Xr shmdt 2 ,
-.Xr shmget 2
+.Xr shmget 2 ,
+.Xr compat 5
projects / apple / xnu.git / blobdiff