Declare and document getthrid()

indirectly prodded by krw@

2 files changed, 82 insertions, 2 deletions

diff --git a/lib/libc/sys/Makefile.inc b/lib/libc/sys/Makefile.inc
index 0fbb0bda402..78535b041fa 100644
--- a/lib/libc/sys/Makefile.inc
+++ b/lib/libc/sys/Makefile.inc
@@ -1,4 +1,4 @@
-#	$OpenBSD: Makefile.inc,v 1.121 2014/08/31 01:42:36 guenther Exp $
+#	$OpenBSD: Makefile.inc,v 1.122 2014/08/31 04:02:08 guenther Exp $
 #	$NetBSD: Makefile.inc,v 1.35 1995/10/16 23:49:07 jtc Exp $
 #	@(#)Makefile.inc	8.1 (Berkeley) 6/17/93
 
@@ -205,7 +205,7 @@ MAN+=	__get_tcb.2 __thrsigdivert.2 __thrsleep.2 _exit.2 accept.2 \
 	getfh.2 getfsstat.2 getgid.2 getgroups.2 getitimer.2 getlogin.2 \
 	getpeername.2 getpgrp.2 getpid.2 getpriority.2 getrlimit.2 \
 	getrtable.2 getrusage.2 getsid.2 getsockname.2 getsockopt.2 \
-	gettimeofday.2 getuid.2 intro.2 ioctl.2 issetugid.2 \
+	getthrid.2 gettimeofday.2 getuid.2 intro.2 ioctl.2 issetugid.2 \
 	kill.2 kqueue.2 ktrace.2 link.2 listen.2 lseek.2 madvise.2 \
 	mincore.2 minherit.2 mkdir.2 mkfifo.2 mknod.2 mlock.2 \
 	mlockall.2 mmap.2 mount.2 mprotect.2 mquery.2 msgctl.2 \
diff --git a/lib/libc/sys/getthrid.2 b/lib/libc/sys/getthrid.2
new file mode 100644
index 00000000000..d92180f82a8
--- /dev/null
+++ b/lib/libc/sys/getthrid.2
@@ -0,0 +1,80 @@
+.\"	$OpenBSD: getthrid.2,v 1.1 2014/08/31 04:02:08 guenther Exp $
+.\"	$NetBSD: getpid.2,v 1.5 1995/02/27 12:33:12 cgd Exp $
+.\"
+.\" Copyright (c) 1980, 1991, 1993
+.\"	The Regents of the University of California.  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.
+.\" 3. Neither the name of the University nor the names of its contributors
+.\"    may be used to endorse or promote products derived from this software
+.\"    without specific prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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.
+.\"
+.\"     @(#)getpid.2	8.1 (Berkeley) 6/4/93
+.\"
+.Dd $Mdocdate: August 31 2014 $
+.Dt GETTHRID 2
+.Os
+.Sh NAME
+.Nm getthrid
+.Nd get thread identifier
+.Sh SYNOPSIS
+.Fd #include <unistd.h>
+.Ft pid_t
+.Fn getthrid void
+.Sh DESCRIPTION
+.Nm
+returns the thread ID of the calling thread.
+This is used in the implementation of the thread library
+.Pq Fl lpthread
+and can appear in the output of system utilities such as
+.Xr ps
+and
+.Xr kdump .
+.Pp
+Thread IDs are not a stable interface and should not be used directly
+by applications except for correlation with system utility output.
+Applications should use the
+.Vt pthread_t
+values from
+.Xr pthread_self
+and
+.Xr pthread_create
+to identify threads within the process itself.
+.Sh RETURN VALUES
+This function is always successful, and no return value is
+reserved to indicate an error.
+.Sh SEE ALSO
+.Xr getpid 2 ,
+.Xr __tfork 2 ,
+.Xr pthread_self 3 ,
+.Xr pthread_create 3
+.Sh STANDARDS
+The
+.Nm
+syscall is specific to
+.Ox
+and should not be used in portable applications.
+.Sh HISTORY
+The
+.Nm
+syscall appeared in
+.Ox 3.9 .