1 files changed, 115 insertions, 0 deletions
diff --git a/man-pages-posix-2003/man3p/ctermid.3p b/man-pages-posix-2003/man3p/ctermid.3p
new file mode 100644
index 0000000..18e46ce
--- /dev/null
+++ b/man-pages-posix-2003/man3p/ctermid.3p
@@ -0,0 +1,115 @@
+.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved 
+.TH "CTERMID" 3P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
+.\" ctermid 
+.SH PROLOG
+This manual page is part of the POSIX Programmer's Manual.
+The Linux implementation of this interface may differ (consult
+the corresponding Linux manual page for details of Linux behavior),
+or the interface may not be implemented on Linux.
+.SH NAME
+ctermid \- generate a pathname for the controlling terminal
+.SH SYNOPSIS
+.LP
+\fB#include <stdio.h>
+.br
+.sp
+char *ctermid(char *\fP\fIs\fP\fB); \fP
+\fB
+.br
+\fP
+.SH DESCRIPTION
+.LP
+The \fIctermid\fP() function shall generate a string that, when used
+as a pathname, refers to the current controlling terminal
+for the current process. If \fIctermid\fP() returns a pathname, access
+to the file is not guaranteed.
+.LP
+If the application uses any of the _POSIX_THREAD_SAFE_FUNCTIONS or
+_POSIX_THREADS functions, it shall ensure that the
+\fIctermid\fP() function is called with a non-NULL parameter.
+.SH RETURN VALUE
+.LP
+If \fIs\fP is a null pointer, the string shall be generated in an
+area that may be static (and therefore may be overwritten by
+each call), the address of which shall be returned. Otherwise, \fIs\fP
+is assumed to point to a character array of at least
+L_ctermid bytes; the string is placed in this array and the value
+of \fIs\fP shall be returned. The symbolic constant L_ctermid is
+defined in \fI<stdio.h>\fP, and shall have a value greater than 0.
+.LP
+The \fIctermid\fP() function shall return an empty string if the pathname
+that would refer to the controlling terminal cannot
+be determined, or if the function is unsuccessful.
+.SH ERRORS
+.LP
+No errors are defined.
+.LP
+\fIThe following sections are informative.\fP
+.SH EXAMPLES
+.SS Determining the Controlling Terminal for the Current Process
+.LP
+The following example returns a pointer to a string that identifies
+the controlling terminal for the current process. The
+pathname for the terminal is stored in the array pointed to by the
+\fIptr\fP argument, which has a size of L_ctermid bytes, as
+indicated by the \fIterm\fP argument.
+.sp
+.RS
+.nf
+
+\fB#include <stdio.h>
+\&...
+char term[L_ctermid];
+char *ptr;
+.sp
+
+ptr = ctermid(term);
+\fP
+.fi
+.RE
+.SH APPLICATION USAGE
+.LP
+The difference between \fIctermid\fP() and \fIttyname\fP() is that
+\fIttyname\fP() must be handed a file descriptor and return a path
+of the terminal associated with
+that file descriptor, while \fIctermid\fP() returns a string (such
+as \fB"/dev/tty"\fP ) that refers to the current controlling
+terminal if used as a pathname.
+.SH RATIONALE
+.LP
+L_ctermid must be defined appropriately for a given implementation
+and must be greater than zero so that array declarations
+using it are accepted by the compiler. The value includes the terminating
+null byte.
+.LP
+Conforming applications that use threads cannot call \fIctermid\fP()
+with NULL as the parameter if either
+_POSIX_THREAD_SAFE_FUNCTIONS or _POSIX_THREADS is defined. If \fIs\fP
+is not NULL, the \fIctermid\fP() function generates a
+string that, when used as a pathname, refers to the current controlling
+terminal for the current process. If \fIs\fP is NULL, the
+return value of \fIctermid\fP() is undefined.
+.LP
+There is no additional burden on the programmer-changing to use a
+hypothetical thread-safe version of \fIctermid\fP() along
+with allocating a buffer is more of a burden than merely allocating
+a buffer. Application code should not assume that the returned
+string is short, as some implementations have more than two pathname
+components before reaching a logical device name.
+.SH FUTURE DIRECTIONS
+.LP
+None.
+.SH SEE ALSO
+.LP
+\fIttyname\fP(), the Base Definitions volume of IEEE\ Std\ 1003.1-2001,
+\fI<stdio.h>\fP
+.SH COPYRIGHT
+Portions of this text are reprinted and reproduced in electronic form
+from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
+-- Portable Operating System Interface (POSIX), The Open Group Base
+Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
+Electrical and Electronics Engineers, Inc and The Open Group. In the
+event of any discrepancy between this version and the original IEEE and
+The Open Group Standard, the original IEEE and The Open Group Standard
+is the referee document. The original Standard can be obtained online at
+http://www.opengroup.org/unix/online.html .