Initial documentation of the internal syscalls that implement the librt

posix semaphores.  As requested in PR kern/37427

XXX Feel free to expand this page!

distrib/sets/lists/comp/mi

@@ -1,4 +1,4 @@
-#	$NetBSD: mi,v 1.2007 2015/11/24 23:33:46 christos Exp $
+#	$NetBSD: mi,v 1.2008 2015/11/29 06:10:01 pgoyette Exp $
 #
 # Note: don't delete entries from here - mark them as "obsolete" instead.
 ./etc/mtree/set.comp				comp-sys-root
@@ -3946,6 +3946,17 @@
 ./usr/share/man/cat2/__quotactl.0		comp-c-catman		.cat
 ./usr/share/man/cat2/__syscall.0		comp-c-catman		.cat
 ./usr/share/man/cat2/_exit.0			comp-c-catman		.cat
+./usr/share/man/cat2/_ksem.0			comp-c-catman		.cat
+./usr/share/man/cat2/_ksem_close.0		comp-c-catman		.cat
+./usr/share/man/cat2/_ksem_destroy.0		comp-c-catman		.cat
+./usr/share/man/cat2/_ksem_getvalue.0		comp-c-catman		.cat
+./usr/share/man/cat2/_ksem_init.0		comp-c-catman		.cat
+./usr/share/man/cat2/_ksem_open.0		comp-c-catman		.cat
+./usr/share/man/cat2/_ksem_post.0		comp-c-catman		.cat
+./usr/share/man/cat2/_ksem_timedwait.0		comp-c-catman		.cat
+./usr/share/man/cat2/_ksem_trywait.0		comp-c-catman		.cat
+./usr/share/man/cat2/_ksem_unlink.0		comp-c-catman		.cat
+./usr/share/man/cat2/_ksem_wait.0		comp-c-catman		.cat
 ./usr/share/man/cat2/_lwp_continue.0		comp-c-catman		.cat
 ./usr/share/man/cat2/_lwp_create.0		comp-c-catman		.cat
 ./usr/share/man/cat2/_lwp_ctl.0			comp-c-catman		.cat
@@ -10987,6 +10998,17 @@
 ./usr/share/man/html2/__quotactl.html		comp-c-htmlman		html
 ./usr/share/man/html2/__syscall.html		comp-c-htmlman		html
 ./usr/share/man/html2/_exit.html		comp-c-htmlman		html
+./usr/share/man/html2/_ksem.html		comp-c-htmlman		html
+./usr/share/man/html2/_ksem_close.html		comp-c-htmlman		html
+./usr/share/man/html2/_ksem_destroy.html	comp-c-htmlman		html
+./usr/share/man/html2/_ksem_getvalue.html	comp-c-htmlman		html
+./usr/share/man/html2/_ksem_init.html		comp-c-htmlman		html
+./usr/share/man/html2/_ksem_open.html		comp-c-htmlman		html
+./usr/share/man/html2/_ksem_post.html		comp-c-htmlman		html
+./usr/share/man/html2/_ksem_timedwait.html	comp-c-htmlman		html
+./usr/share/man/html2/_ksem_trywait.html	comp-c-htmlman		html
+./usr/share/man/html2/_ksem_unlink.html		comp-c-htmlman		html
+./usr/share/man/html2/_ksem_wait.html		comp-c-htmlman		html
 ./usr/share/man/html2/_lwp_continue.html	comp-c-htmlman		html
 ./usr/share/man/html2/_lwp_create.html		comp-c-htmlman		html
 ./usr/share/man/html2/_lwp_ctl.html		comp-c-htmlman		html
@@ -17791,6 +17813,17 @@
 ./usr/share/man/man2/__quotactl.2		comp-c-man		.man
 ./usr/share/man/man2/__syscall.2		comp-c-man		.man
 ./usr/share/man/man2/_exit.2			comp-c-man		.man
+./usr/share/man/man2/_ksem.2			comp-c-man		.man
+./usr/share/man/man2/_ksem_close.2		comp-c-man		.man
+./usr/share/man/man2/_ksem_destroy.2		comp-c-man		.man
+./usr/share/man/man2/_ksem_getvalue.2		comp-c-man		.man
+./usr/share/man/man2/_ksem_init.2		comp-c-man		.man
+./usr/share/man/man2/_ksem_open.2		comp-c-man		.man
+./usr/share/man/man2/_ksem_post.2		comp-c-man		.man
+./usr/share/man/man2/_ksem_timedwait.2		comp-c-man		.man
+./usr/share/man/man2/_ksem_trywait.2		comp-c-man		.man
+./usr/share/man/man2/_ksem_unlink.2		comp-c-man		.man
+./usr/share/man/man2/_ksem_wait.2		comp-c-man		.man
 ./usr/share/man/man2/_lwp_continue.2		comp-c-man		.man
 ./usr/share/man/man2/_lwp_create.2		comp-c-man		.man
 ./usr/share/man/man2/_lwp_ctl.2			comp-c-man		.man

lib/libc/sys/Makefile.inc

@@ -1,4 +1,4 @@
-#	$NetBSD: Makefile.inc,v 1.227 2015/01/31 23:10:56 christos Exp $
+#	$NetBSD: Makefile.inc,v 1.228 2015/11/29 06:10:01 pgoyette Exp $
 #	@(#)Makefile.inc	8.3 (Berkeley) 10/24/94
 
 # sys sources
@@ -249,7 +249,7 @@ MAN+=	accept.2 access.2 acct.2 adjtime.2 bind.2 brk.2 chdir.2 \
 	getitimer.2 getlogin.2 getpeername.2 getpgrp.2 getpid.2 \
 	getpriority.2 getrlimit.2 getrusage.2 getsid.2 getsockname.2 \
 	getsockopt.2 gettimeofday.2 getuid.2 intro.2 ioctl.2 issetugid.2 \
-	kill.2 kqueue.2 ktrace.2 \
+	kill.2 kqueue.2 ktrace.2 _ksem.2 \
 	lfs_bmapv.2 lfs_markv.2 lfs_segclean.2 lfs_segwait.2 \
 	link.2 listen.2 lseek.2 \
 	_lwp_create.2 _lwp_ctl.2 _lwp_detach.2 _lwp_exit.2 \
@@ -321,6 +321,16 @@ MLINKS+=gettimeofday.2 settimeofday.2
 MLINKS+=getuid.2 geteuid.2
 MLINKS+=intro.2 errno.2
 MLINKS+=kqueue.2 kevent.2
+MLINKS+=_ksem.2 _ksem_open.2
+MLINKS+=_ksem.2 _ksem_close.2
+MLINKS+=_ksem.2 _ksem_init.2
+MLINKS+=_ksem.2 _ksem_destroy.2
+MLINKS+=_ksem.2 _ksem_getvalue.2
+MLINKS+=_ksem.2 _ksem_post.2
+MLINKS+=_ksem.2 _ksem_wait.2
+MLINKS+=_ksem.2 _ksem_timedwait.2
+MLINKS+=_ksem.2 _ksem_trywait.2
+MLINKS+=_ksem.2 _ksem_unlink.2
 MLINKS+=ktrace.2 fktrace.2
 MLINKS+=lseek.2 seek.2
 MLINKS+=link.2 linkat.2

lib/libc/sys/_ksem.2

@@ -0,0 +1,97 @@
+.\"	$NetBSD: _ksem.2,v 1.1 2015/11/29 06:10:01 pgoyette Exp $
+.\"
+.\" Copyright (c) 2015 The NetBSD Foundation, Inc.
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
+.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
+.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+.\" POSSIBILITY OF SUCH DAMAGE.
+.\"
+.Dd November 30, 2015
+.Dt _KSEM 2
+.Os
+.Sh NAME
+.Nm _ksem ,
+.Nm _ksem_init ,
+.Nm _ksem_open ,
+.Nm _ksem_close ,
+.Nm _ksem_unlink ,
+.Nm _ksem_destroy ,
+.Nm _ksem_getvalue ,
+.Nm _ksem_post ,
+.Nm _ksem_wait ,
+.Nm _ksem_timedwait ,
+.Nm _ksem_trywait
+.Nd back-end implementation for POSIX semaphores
+.Sh SYNOPSIS
+.In sys/ksem.h
+.Ft int
+.Fn _ksem_init "int value" "intptr_t *idp"
+.Ft int     
+.Fn _ksem_open "const char *name" "int oflag" "mode_t mode" "unsigned int value" "intptr_t *idp"
+.Ft int
+.Fn _ksem_close "intptr_t id"
+.Ft int
+.Fn _ksem_unlink "const char *name"
+.Ft int
+.Fn _ksem_destroy "intptr_t id"
+.Ft int
+.Fn _ksem_getvalue "intptr_t id" "unsigned int *value"
+.Ft int
+.Fn _ksem_post "intptr_t id"
+.Ft int
+.Fn _ksem_wait "intptr_t id"
+.Ft int
+.Fn _ksem_timedwait "intptr_t id" "const struct timespec *abstime"
+.Ft int
+.Fn _ksem_trywait "intptr_t id"
+.Sh DESCRIPTION
+The
+.Fn _ksem_*
+family of system calls provide the kernel implementation of POSIX
+semaphores.
+.Sh RETURN VALUES
+Successful calls to the
+.Fn _ksem_*
+system calls return a value of zero.
+Otherwise, \-1 is returned and
+.Va errno
+is set to provide more information.
+.Sh ERRORS
+Please see the section 3 manual pages for specific error information.
+.Sh SEE ALSO
+.Xr sem_close 3 ,
+.Xr sem_destroy 3 ,
+.Xr sem_getvalue 3 ,
+.Xr sem_init 3 ,
+.Xr sem_open 3 ,
+.Xr sem_post 3 ,
+.Xr sem_unlink 3 ,
+.Xr sem_wait 3 ,
+.Xr sem 4
+.Sh HISTORY
+Most of the
+.Fn _ksem_*
+system calls first appeared in
+.Nx 2.0 .
+The
+.Fn _ksem_timedwait
+system call first appeared in
+.Nx 5.0 .