diff options
| -rw-r--r-- | ChangeLog | 7 | ||||
| -rw-r--r-- | manual/Makefile | 4 | ||||
| -rw-r--r-- | manual/ipc.texi | 116 | ||||
| -rw-r--r-- | manual/job.texi | 2 | ||||
| -rw-r--r-- | manual/process.texi | 2 |
5 files changed, 127 insertions, 4 deletions
@@ -1,3 +1,10 @@ +2014-02-26 Carlos O'Donell <carlos@redhat.com> + + * manual/ipc.texi: New file. + * manual/Makefile (chapters): Add ipc. + * manual/job.texi: Add "Inter-Process Communication" to next. + * manual/process.texi: Add "Inter-Process Communication" to prev. + 2014-02-26 Adhemerval Zanella <azanella@linux.vnet.ibm.com> * sysdeps/powerpc/fpu/libm-test-ulps: Update. diff --git a/manual/Makefile b/manual/Makefile index 5f98b2abf8..1129136c89 100644 --- a/manual/Makefile +++ b/manual/Makefile @@ -41,8 +41,8 @@ chapters = $(addsuffix .texi, \ intro errno memory ctype string charset locale \ message search pattern io stdio llio filesys \ pipe socket terminal syslog math arith time \ - resource setjmp signal startup process job nss \ - users sysinfo conf crypt debug threads probes) + resource setjmp signal startup process ipc job \ + nss users sysinfo conf crypt debug threads probes) add-chapters = $(wildcard $(foreach d, $(add-ons), ../$d/$d.texi)) appendices = lang.texi header.texi install.texi maint.texi platform.texi \ contrib.texi diff --git a/manual/ipc.texi b/manual/ipc.texi new file mode 100644 index 0000000000..3cd573ea6d --- /dev/null +++ b/manual/ipc.texi @@ -0,0 +1,116 @@ +@node Inter-Process Communication, Job Control, Processes, Top +@c %MENU% All about inter-process communication +@chapter Inter-Process Communication +@cindex ipc + +This chapter describes the @glibcadj{} inter-process communication primitives. + +@menu +* Semaphores:: Support for creating and managing semaphores +@end menu + +@node Semaphores +@section Semaphores + +The @glibcadj{} implements the semaphore APIs as defined in POSIX and +System V. Semaphores can be used by multiple processes to coordinate shared +resources. The following is a complete list of the semaphore functions provided +by @theglibc{}. + +@c Need descriptions for all of these functions. + +@subsection System V Semaphores +@deftypefun int semctl (int @var{semid}, int @var{semnum}, int @var{cmd}); +@safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@acucorrupt{/linux}}} +@c syscall(ipc) ok +@c +@c AC-unsafe because we need to translate the new kernel +@c semid_ds buf into the userspace layout. Cancellation +@c at that point results in an inconsistent userspace +@c semid_ds. +@end deftypefun + +@deftypefun int semget (key_t @var{key}, int @var{nsems}, int @var{semflg}); +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c syscall(ipc) ok +@end deftypefun + +@deftypefun int semop (int @var{semid}, struct sembuf *@var{sops}, size_t @var{nsops}); +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c syscall(ipc) ok +@end deftypefun + +@deftypefun int semtimedop (int @var{semid}, struct sembuf *@var{sops}, size_t @var{nsops}, const struct timespec *@var{timeout}); +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c syscall(ipc) ok +@end deftypefun + +@subsection POSIX Semaphores + +@deftypefun int sem_init (sem_t *@var{sem}, int @var{pshared}, unsigned int @var{value}); +@safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@acucorrupt{}}} +@c Does not atomically update sem_t therefore AC-unsafe +@c because it can leave sem_t partially initialized. +@end deftypefun + +@deftypefun int sem_destroy (sem_t *@var{sem}); +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c Function does nothing and is therefore always safe. +@end deftypefun + +@deftypefun sem_t *sem_open (const char *@var{name}, int @var{oflag}, ...); +@safety{@prelim{}@mtsafe{}@asunsafe{@asuinit{}}@acunsafe{@acuinit{}}} +@c pthread_once asuinit +@c +@c We are AC-Unsafe becuase we use pthread_once to initialize +@c a global variable that holds the location of the mounted +@c shmfs on Linux. +@end deftypefun + +@deftypefun int sem_close (sem_t *@var{sem}); +@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@asucorrupt{}}} +@c lll_lock asulock aculock +@c twalk asucorrupt +@c +@c We are AS-unsafe because we take a non-recursive lock. +@c We are AC-unsafe because several internal data structures +@c are not updated atomically. +@end deftypefun + +@deftypefun int sem_unlink (const char *@var{name}); +@safety{@prelim{}@mtsafe{}@asunsafe{@asuinit{}}@acunsafe{@acucorrupt{}}} +@c pthread_once asuinit acucorrupt aculock +@c mempcpy acucorrupt +@end deftypefun + +@deftypefun int sem_wait (sem_t *@var{sem}); +@safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@acucorrupt{}}} +@c atomic_increment (nwaiters) acucorrupt +@c +@c Given the use atomic operations this function seems +@c to be AS-safe. It is AC-unsafe because there is still +@c a window between atomic_decrement and the pthread_push +@c of the handler that undoes that operation. A cancellation +@c at that point would fail to remove the process from the +@c waiters count. +@end deftypefun + +@deftypefun int sem_timedwait (sem_t *@var{sem}, const struct timespec *@var{abstime}); +@safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@acucorrupt{}}} +@c Same safety issues as sem_wait. +@end deftypefun + +@deftypefun int sem_trywait (sem_t *@var{sem}); +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c All atomic operations are safe in all contexts. +@end deftypefun + +@deftypefun int sem_post (sem_t *@var{sem}); +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c Same safety as sem_trywait. +@end deftypefun + +@deftypefun int sem_getvalue (sem_t *@var{sem}, int *@var{sval}); +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +@c Atomic write of a value is safe in all contexts. +@end deftypefun diff --git a/manual/job.texi b/manual/job.texi index 4e58f54e9c..4f9bd81ffe 100644 --- a/manual/job.texi +++ b/manual/job.texi @@ -1,4 +1,4 @@ -@node Job Control, Name Service Switch, Processes, Top +@node Job Control, Name Service Switch, Inter-Process Communication, Top @c %MENU% All about process groups and sessions @chapter Job Control diff --git a/manual/process.texi b/manual/process.texi index aee65b9738..aa59040cb4 100644 --- a/manual/process.texi +++ b/manual/process.texi @@ -1,4 +1,4 @@ -@node Processes, Job Control, Program Basics, Top +@node Processes, Inter-Process Communication, Program Basics, Top @c %MENU% How to create processes and run other programs @chapter Processes |