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
6This 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
16System V.  Semaphores can be used by multiple processes to coordinate shared
17resources.  The following is a complete list of the semaphore functions provided
18by @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
117