]>
Commit | Line | Data |
---|---|---|
085d0e35 CD |
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 | ||
f067bf1f | 15 | @Theglibc{} implements the semaphore APIs as defined in POSIX and |
085d0e35 CD |
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}); | |
862c472e | 71 | @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} |
085d0e35 | 72 | @c lll_lock asulock aculock |
862c472e | 73 | @c twalk mtsrace{:root} |
085d0e35 CD |
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{}}} | |
d1babeb3 | 88 | @c atomic_fetch_add_relaxed (nwaiters) acucorrupt |
085d0e35 CD |
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 | |
a364a3a7 | 92 | @c a window between atomic_fetch_add_relaxed and the pthread_push |
085d0e35 CD |
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 |