manual/ipc.texi

   1 @node Inter-Process Communication, Job Control, Processes, Top
   2 @c %MENU% All about inter-process communication
   3 @chapter Inter-Process Communication
   4 @cindex ipc
   5
   6 This chapter describes the @glibcadj{} inter-process communication primitives.
   7
   8 @menu
   9 * Semaphores::  Support for creating and managing semaphores
  10 @end menu
  11
  12 @node Semaphores
  13 @section Semaphores
  14
  15 @Theglibc{} implements the semaphore APIs as defined in POSIX and
  16 System V.  Semaphores can be used by multiple processes to coordinate shared
  17 resources.  The following is a complete list of the semaphore functions provided
  18 by @theglibc{}.
  19
  20 @c Need descriptions for all of these functions.
  21
  22 @subsection System V Semaphores
  23 @deftypefun int semctl (int @var{semid}, int @var{semnum}, int @var{cmd});
  24 @safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@acucorrupt{/linux}}}
  25 @c syscall(ipc) ok
  26 @c
  27 @c AC-unsafe because we need to translate the new kernel
  28 @c semid_ds buf into the userspace layout.  Cancellation
  29 @c at that point results in an inconsistent userspace
  30 @c semid_ds.
  31 @end deftypefun
  32
  33 @deftypefun int semget (key_t @var{key}, int @var{nsems}, int @var{semflg});
  34 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
  35 @c syscall(ipc) ok
  36 @end deftypefun
  37
  38 @deftypefun int semop (int @var{semid}, struct sembuf *@var{sops}, size_t @var{nsops});
  39 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
  40 @c syscall(ipc) ok
  41 @end deftypefun
  42
  43 @deftypefun int semtimedop (int @var{semid}, struct sembuf *@var{sops}, size_t @var{nsops}, const struct timespec *@var{timeout});
  44 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
  45 @c syscall(ipc) ok
  46 @end deftypefun
  47
  48 @subsection POSIX Semaphores
  49
  50 @deftypefun int sem_init (sem_t *@var{sem}, int @var{pshared}, unsigned int @var{value});
  51 @safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@acucorrupt{}}}
  52 @c Does not atomically update sem_t therefore AC-unsafe
  53 @c because it can leave sem_t partially initialized.
  54 @end deftypefun
  55
  56 @deftypefun int sem_destroy (sem_t *@var{sem});
  57 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
  58 @c Function does nothing and is therefore always safe.
  59 @end deftypefun
  60
  61 @deftypefun sem_t *sem_open (const char *@var{name}, int @var{oflag}, ...);
  62 @safety{@prelim{}@mtsafe{}@asunsafe{@asuinit{}}@acunsafe{@acuinit{}}}
  63 @c pthread_once asuinit
  64 @c
  65 @c We are AC-Unsafe becuase we use pthread_once to initialize
  66 @c a global variable that holds the location of the mounted
  67 @c shmfs on Linux.
  68 @end deftypefun
  69
  70 @deftypefun int sem_close (sem_t *@var{sem});
  71 @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}}
  72 @c lll_lock asulock aculock
  73 @c twalk mtsrace{:root}
  74 @c
  75 @c We are AS-unsafe because we take a non-recursive lock.
  76 @c We are AC-unsafe because several internal data structures
  77 @c are not updated atomically.
  78 @end deftypefun
  79
  80 @deftypefun int sem_unlink (const char *@var{name});
  81 @safety{@prelim{}@mtsafe{}@asunsafe{@asuinit{}}@acunsafe{@acucorrupt{}}}
  82 @c pthread_once asuinit acucorrupt aculock
  83 @c mempcpy acucorrupt
  84 @end deftypefun
  85
  86 @deftypefun int sem_wait (sem_t *@var{sem});
  87 @safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@acucorrupt{}}}
  88 @c atomic_increment (nwaiters) acucorrupt
  89 @c
  90 @c Given the use atomic operations this function seems
  91 @c to be AS-safe.  It is AC-unsafe because there is still
  92 @c a window between atomic_decrement and the pthread_push
  93 @c of the handler that undoes that operation.  A cancellation
  94 @c at that point would fail to remove the process from the
  95 @c waiters count.
  96 @end deftypefun
  97
  98 @deftypefun int sem_timedwait (sem_t *@var{sem}, const struct timespec *@var{abstime});
  99 @safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@acucorrupt{}}}
 100 @c Same safety issues as sem_wait.
 101 @end deftypefun
 102
 103 @deftypefun int sem_trywait (sem_t *@var{sem});
 104 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
 105 @c All atomic operations are safe in all contexts.
 106 @end deftypefun
 107
 108 @deftypefun int sem_post (sem_t *@var{sem});
 109 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
 110 @c Same safety as sem_trywait.
 111 @end deftypefun
 112
 113 @deftypefun int sem_getvalue (sem_t *@var{sem}, int *@var{sval});
 114 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
 115 @c Atomic write of a value is safe in all contexts.
 116 @end deftypefun