This is the mail archive of the libc-alpha@sourceware.org mailing list for the glibc project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

[PATCH] Add "Inter-process Communication" chapter to the glibc manual.


We do not document any of the sem* functions provided by glibc.

The following patch adds all 14 sem* functions to the manual
under a new chapter called "Inter-Process Communication."

The 14 sem* functions are added under "Semaphores" section which
contains "System V Sempahores" and "POSIX Seamphores" sub-sections.

The functions include only their signature and safety information
(as audited by me). We still need to fill in the details for the
functions, but this is better than nothing IMO.

Comments on the chapter/section/sub-section naming or placement?

Manual builds in pdf, html, and info with no problems and
navigates correctly and looks good.

OK to checkin?

Still to be done are msg* and shm* functions, which are
another 8 functions.

One might object to the name "System V Sempahores" and instead
wish to lump them into "XSI Interprocess Communication" as defined
in POSIX. However, I found it seemed more natural to call them
"System V Semaphores," owing perhaps to my experience with them
under that name initially.

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.

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..ea4e1ec
--- /dev/null
+++ b/manual/ipc.texi
@@ -0,0 +1,115 @@
+@node Inter-Process Communication, Job Control, Processes, Top
+@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
 
---
Cheers,
Carlos.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]