From: Carlos O'Donell Date: Wed, 26 Feb 2014 16:03:24 +0000 (-0500) Subject: Add a new "Inter-Process Communication" chapter. X-Git-Tag: glibc-2.20~828 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=085d0e354a84807ca97f8720e532763bd4bfa933;p=platform%2Fupstream%2Fglibc.git Add a new "Inter-Process Communication" chapter. This patch adds a new "Inter-Process Communication" chapter to cover the sem*, msg*, and shm* functions. Initially we document only the sem* function signatures and their safety notes. --- diff --git a/ChangeLog b/ChangeLog index 02ca836..9505934 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,10 @@ +2014-02-26 Carlos O'Donell + + * 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 * sysdeps/powerpc/fpu/libm-test-ulps: Update. diff --git a/manual/Makefile b/manual/Makefile index 5f98b2a..1129136 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 0000000..3cd573e --- /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 4e58f54..4f9bd81 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 aee65b9..aa59040 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