xnu-1228.7.58.tar.gz

[apple/xnu.git] / bsd / man / man2 / shmctl.2

diff --git a/bsd/man/man2/shmctl.2 b/bsd/man/man2/shmctl.2
index 036db38b3e93ea11f204bf0f3a2d0bc041dbb3e2..0af2016edd8fed3a78ce99008344594ab06458c9 100644 (file)
--- a/bsd/man/man2/shmctl.2
+++ b/bsd/man/man2/shmctl.2
@@ -37,39 +37,40 @@
 .Nm shmctl
 .Nd shared memory control operations
 .Sh SYNOPSIS
 .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
 .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 .
 .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 .
 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 {
 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
 };
 .Ed

+.Pp

 The
 .Bf -literal
 ipc_perm
 The
 .Bf -literal
 ipc_perm


@@ -83,16 +84,16 @@ structure is defined in
 and looks like this:
 .Bd -literal
 struct 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
 };
 .Ed

-
+.Pp

 The operation to be performed by
 .Fn shmctl
 is specified in
 The operation to be performed by
 .Fn shmctl
 is specified in


@@ -120,7 +121,6 @@ has an effective user id equal to either
 or
 .Va shm_perm.uid
 in the data structure associated with the shared memory segment.
 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
 .It Dv IPC_RMID
 Remove the shared memory segment specified by
 .Fa shmid


@@ -131,7 +131,7 @@ or
 .Va shm_perm.uid
 values in the data structure associated with the queue can do this.
 .El
 .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
 The read and write permissions on a shared memory identifier
 are determined by the
 .Va shm_perm.mode


@@ -148,41 +148,83 @@ effective gid can match either
 or
 .Va shm_perm.gid .
 .Sh RETURN VALUES
 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
 .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
 .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.
 .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.
 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
 .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 ,
 .Sh SEE ALSO
 .Xr shmat 2 ,
 .Xr shmdt 2 ,

-.Xr shmget 2
+.Xr shmget 2 ,
+.Xr compat 5