ipc.texi

Util-linux 软件包包含许多工具。其中比较重要的是加载、卸载、格式化、分区和管理硬盘驱动器

@example
int msgsnd (int msqid, struct msgbuf *msgp, int msgsz, int msgflg);
@end example

@itemize @bullet
@item
@code{msqid} : id obtained by a call to msgget.
@item
@code{msgsz} : size of msg text (@code{mtext}) in bytes.
@item
@code{msgp} : message to be sent. (msgp->mtype must be positive).
@item
@code{msgflg} : IPC_NOWAIT.
@item
returns : msgsz on success. -1 on error.
@end itemize

The message text and type are stored in the internal @code{msg}
structure. @code{msg_cbytes}, @code{msg_qnum}, @code{msg_lspid},
and @code{msg_stime} fields are updated. Readers waiting on the
queue are awakened.@refill

@noindent
Errors:@*
@noindent
EACCES : Do not have write permission on queue.@*
@noindent
EAGAIN : IPC_NOWAIT specified and queue is full.@*
@noindent
EFAULT : msgp not accessible.@*
@noindent
EIDRM  : The message queue was removed.@*
@noindent
EINTR  : Full queue ... would have slept but ... was interrupted.@*
@noindent
EINVAL : mtype < 1, msgsz > MSGMAX, msgsz < 0, msqid < 0 or unused.@*
@noindent
ENOMEM : Could not allocate space for header and text.@*



@node msgrcv, msgctl, msgsnd, Messages
@subsection msgrcv

@example
int msgrcv (int msqid, struct msgbuf *msgp, int msgsz, long msgtyp,
			int msgflg);
@end example

@itemize @bullet
@item
msqid  : id obtained by a call to msgget.
@item
msgsz  : maximum size of message to receive.
@item
msgp   : allocated by user to store the message in.
@item
msgtyp :
@itemize @asis
@item
0 => get first message on queue.
@item
> 0 => get first message of matching type.
@item
< 0 => get message with least type  which is <= abs(msgtyp). 
@end itemize
@item
msgflg :
@itemize @asis
@item
IPC_NOWAIT : Return immediately if message not found.
@item
MSG_NOERROR : The message is truncated if it is larger than msgsz.
@item
MSG_EXCEPT : Used with msgtyp > 0 to receive any msg except of specified
type.@refill
@end itemize
@item
returns : size of message if found. -1 on error.
@end itemize

The first message that meets the @code{msgtyp} specification is
identified. For msgtyp < 0, the entire queue is searched for the
message with the smallest type.@refill

If its length is smaller than msgsz or if the user specified the
MSG_NOERROR flag, its text and type are copied to msgp->mtext and
msgp->mtype, and it is taken off the queue.@refill

The @code{msg_cbytes}, @code{msg_qnum}, @code{msg_lrpid},
and @code{msg_rtime} fields are updated. Writers waiting on the
queue are awakened.@refill

@noindent
Errors:@*
@noindent
E2BIG  : msg bigger than msgsz and MSG_NOERROR not specified.@*
@noindent
EACCES : Do not have permission for reading the queue.@*
@noindent
EFAULT : msgp not accessible.@*
@noindent
EIDRM  : msg queue was removed.@*
@noindent
EINTR  : msg not found ... would have slept but ... was interrupted.@*
@noindent
EINVAL : msgsz > msgmax or msgsz < 0, msqid < 0 or unused.@*
@noindent
ENOMSG : msg of requested type not found and IPC_NOWAIT specified.



@node msgctl, msglimits, msgrcv, Messages
@subsection msgctl

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

@itemize @bullet
@item
msqid  : id obtained by a call to msgget.
@item
buf    : allocated by user for reading/writing info.
@item
cmd    : IPC_STAT, IPC_SET, IPC_RMID (@xref{syscalls}).
@end itemize

IPC_STAT results in the copy of the queue data structure
into the user supplied buffer.@refill

In the case of IPC_SET, the queue size (@code{msg_qbytes})
and the @code{uid}, @code{gid}, @code{mode} (low 9 bits) fields
of the @code{msg_perm} struct are set from the user supplied values.
@code{msg_ctime} is updated.@refill

Note that only the super user may increase the limit on the size of a
message queue beyond MSGMNB.@refill

When the queue is destroyed (IPC_RMID), the sequence number is
incremented and all waiting readers and writers are awakened.
These processes will then return with @code{errno} set to EIDRM.@refill

@noindent
Errors:
@noindent
EPERM  : Insufficient privilege to increase the size of the queue (IPC_SET)
or remove it (IPC_RMID).@*
@noindent
EACCES : Do not have permission for reading the queue (IPC_STAT).@*
@noindent
EFAULT : buf not accessible (IPC_STAT, IPC_SET).@*
@noindent
EIDRM  : msg queue was removed.@*
@noindent
EINVAL : invalid cmd, msqid < 0 or unused.


@node msglimits, Semaphores, msgctl, Messages
@subsection Limis on Message Resources

@noindent
Sizeof various structures:
@itemize @asis
@item
msqid_ds        52   /* 1 per message  queue .. dynamic */
@item
msg             16   /* 1 for each message in system .. dynamic */
@item
msgbuf           8   /* allocated by user */
@end itemize

@noindent
Limits
@itemize @bullet
@item
MSGMNI : number of message queue identifiers ... policy.
@item
MSGMAX : max size of message.
Header and message space allocated on one page.
MSGMAX = (PAGE_SIZE - sizeof(struct msg)).
Implementation maximum MSGMAX = 4080.@refill
@item
MSGMNB : default max size of a message queue ... policy.
The super-user can increase the size of a
queue beyond MSGMNB by a @code{msgctl} call.@refill
@end itemize

@noindent
Unused or unimplemented:@*
MSGTQL  max number of message headers system-wide.@*
MSGPOOL total size in bytes of msg pool.


 
@node Semaphores, semget, msglimits, Top
@section Semaphores

Each semaphore has a value >= 0. An id provides access to an array
of @code{nsems} semaphores. Operations such as read, increment or decrement
semaphores in a set are performed by the @code{semop} call which processes
@code{nsops} operations at a time. Each operation is specified in a struct
@code{sembuf} described below. The operations are applied only if all of
them succeed.@refill

If you do not have a need for such arrays, you are probably better off using
the @code{test_bit}, @code{set_bit} and  @code{clear_bit} bit-operations
defined in <asm/bitops.h>.@refill

Semaphore operations may also be qualified by a SEM_UNDO flag which
results in the operation being undone when the process exits.@refill

If a decrement cannot go through, a process will be put to sleep
on a queue waiting for the @code{semval} to increase unless it specifies
IPC_NOWAIT. A read operation can similarly result in a sleep on a
queue waiting for @code{semval} to become 0. (Actually there are
two queues per semaphore array).@refill 

@noindent
A semaphore array is described by:
@example
struct semid_ds
  struct ipc_perm sem_perm;      
  time_t          sem_otime;      /* last semop time */
  time_t          sem_ctime;      /* last change time */
  struct wait_queue *eventn;	  /* wait for a semval to increase */
  struct wait_queue *eventz;      /* wait for a semval to become 0 */
  struct sem_undo  *undo;         /* undo entries */
  ushort          sem_nsems;      /* no. of semaphores in array */
@end example

@noindent
Each semaphore is described internally by :
@example
struct sem
  short   sempid;         /* pid of last semop() */
  ushort  semval;         /* current value */
  ushort  semncnt;        /* num procs awaiting increase in semval */
  ushort  semzcnt;        /* num procs awaiting semval = 0 */
@end example

@menu
* semget::
* semop::
* semctl::
* semlimits:: Limits imposed by this implementation.
@end menu

@node semget, semop, Semaphores, Semaphores
@subsection semget

@noindent
A semaphore array is allocated by a semget system call:

@example
semid = semget (key_t key, int nsems, int semflg);
@end example

@itemize @bullet
@item
@code{key} : an integer usually got from @code{ftok} or IPC_PRIVATE
@item
@code{nsems} :
@itemize @asis
@item
# of semaphores in array (0 <= nsems <= SEMMSL <= SEMMNS)
@item
0 => dont care can be used when not creating the resource.
If successful you always get access to the entire array anyway.@refill
@end itemize
@item
semflg :
@itemize @asis
@item
IPC_CREAT used to create a new resource
@item
IPC_EXCL used with IPC_CREAT to ensure failure if the resource exists.
@item
rwxrwxrwx  access permissions.
@end itemize
@item
returns : semid on success. -1 on failure.
@end itemize

An array of nsems semaphores is allocated if there is no resource
corresponding to the given key. The access permissions specified are
then copied into the @code{sem_perm} struct for the array along with the
user-id etc. The user must use the IPC_CREAT flag or key = IPC_PRIVATE
if a new resource is to be created.@refill

@noindent
Errors:@*
@noindent
EINVAL : nsems not in above range (allocate).@*
       nsems greater than number in array (procure).@*
@noindent
EEXIST : (allocate) IPC_CREAT | IPC_EXCL specified and resource exists.@*
@noindent
EIDRM  : (procure) The resource was removed.@*
@noindent
ENOMEM : could not allocate space for semaphore array.@*
@noindent
ENOSPC : No arrays available (SEMMNI), too few semaphores available (SEMMNS).@*
@noindent
ENOENT : Resource does not exist and IPC_CREAT not specified.@*
@noindent
EACCES : (procure) do not have permission for specified access.


@node semop, semctl, semget, Semaphores
@subsection semop

@noindent
Operations on semaphore arrays are performed by calling semop :

@example
int semop (int semid, struct sembuf *sops, unsigned nsops);
@end example
@itemize @bullet
@item
semid : id obtained by a call to semget.
@item
sops : array of semaphore operations.
@item
nsops : number of operations in array (0 < nsops < SEMOPM).
@item
returns : semval for last operation. -1 on failure.
@end itemize

@noindent
Operations are described by a structure sembuf:
@example
struct sembuf
    ushort  sem_num;        /* semaphore index in array */
    short   sem_op;         /* semaphore operation */
    short   sem_flg;        /* operation flags */
@end example

The value @code{sem_op} is to be added (signed) to the current value semval
of the semaphore with index sem_num (0 .. nsems -1) in the set.
Flags recognized in sem_flg are IPC_NOWAIT and SEM_UNDO.@refill

@noindent
Two kinds of operations can result in wait:
@enumerate
@item
If sem_op is 0 (read operation) and semval is non-zero, the process
sleeps on a queue waiting for semval to become zero or returns with
error EAGAIN if (IPC_NOWAIT | sem_flg) is true.@refill
@item
If (sem_op < 0) and (semval + sem_op < 0), the process either sleeps
on a queue waiting for semval to increase or returns with error EAGAIN if
(sem_flg & IPC_NOWAIT) is true.@refill
@end enumerate

The array sops is first read in and preliminary checks performed on
the arguments. The operations are parsed to determine if any of
them needs write permissions or requests an undo operation.@refill

The operations are then tried and the process sleeps if any operation
that does not specify IPC_NOWAIT cannot go through. If a process sleeps
it repeats these checks on waking up. If any operation that requests
IPC_NOWAIT, cannot go through at any stage, the call returns with errno
set to EAGAIN.@refill

Finally, operations are committed when all go through without an intervening
sleep. Processes waiting on the zero_queue or increment_queue are awakened
if any of the semval's becomes zero or is incremented respectively.@refill

@noindent
Errors:@*
@noindent
E2BIG  : nsops > SEMOPM.@*
@noindent
EACCES : Do not have permission for requested (read/alter) access.@*
@noindent
EAGAIN : An operation with IPC_NOWAIT specified could not go through.@*
@noindent
EFAULT : The array sops is not accessible.@*
@noindent
EFBIG  : An operation had semnum >= nsems.@*
@noindent
EIDRM  : The resource was removed.@*
@noindent
EINTR  : The process was interrupted on its way to a wait queue.@*
@noindent
EINVAL : nsops is 0, semid < 0 or unused.@*
@noindent
ENOMEM : SEM_UNDO requested. Could not allocate space for undo structure.@*
@noindent
ERANGE : sem_op + semval > SEMVMX for some operation.


@node semctl, semlimits, semop, Semaphores
@subsection semctl

@example
int semctl (int semid, int semnum, int cmd, union semun arg);
@end example

@itemize @bullet
@item
semid : id obtained by a call to semget.
@item
cmd :
@itemize @asis
@item 
GETPID  return pid for the process that executed the last semop.
@item 
GETVAL  return semval of semaphore with index semnum.
@item 
GETNCNT return number of processes waiting for semval to increase.
@item 
GETZCNT return number of processes waiting for semval to become 0
@item 
SETVAL  set semval = arg.val.
@item 
GETALL  read all semval's into arg.array.
@item 
SETALL  set all semval's with values given in arg.array.
@end itemize
@item
returns : 0 on success or as given above. -1 on failure.
@end itemize

The first 4 operate on the semaphore with index semnum in the set.
The last two operate on all semaphores in the set.@refill

@code{arg} is a union :
@example
union semun
    int val;               value for SETVAL.
    struct semid_ds *buf;  buffer for IPC_STAT and IPC_SET.
    ushort *array;         array for GETALL and SETALL
@end example

@itemize @bullet
@item