.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved 
.TH "CTERMID" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\" ctermid 
.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 .