The Open Group Base Specifications Issue 6
IEEE Std 1003.1, 2004 Edition
Copyright © 2001-2004 The IEEE and The Open Group, All Rights reserved.

#### NAME

> ctermid - generate a pathname for the controlling terminal

#### SYNOPSIS

> ``[CX] #include <stdio.h>
> char *ctermid(char *`s`);``
> `
> `

#### DESCRIPTION

> The ctermid() function shall generate a string that, when used as a pathname, refers to the current controlling terminal for the current process. If ctermid() returns a pathname, access to the file is not guaranteed.

> If the application uses any of the _POSIX_THREAD_SAFE_FUNCTIONS or _POSIX_THREADS functions, it shall ensure that the ctermid() function is called with a non-NULL parameter.

#### RETURN VALUE

> If s 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, s 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 s shall be returned. The symbolic constant L_ctermid is defined in <stdio.h>, and shall have a value greater than 0.

> The ctermid() 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.

#### ERRORS

> No errors are defined.

The following sections are informative.

#### EXAMPLES

> ##### Determining the Controlling Terminal for the Current Process

> 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 ptr argument, which has a size of L_ctermid bytes, as indicated by the term argument.

>     #include <stdio.h>
>     ...
>     char term[L_ctermid];
>     char *ptr;

>     ptr = ctermid(term);

#### APPLICATION USAGE

> The difference between ctermid() and ttyname() is that ttyname() must be handed a file descriptor and return a path of the terminal associated with that file descriptor, while ctermid() returns a string (such as `"/dev/tty"` ) that refers to the current controlling terminal if used as a pathname.

#### RATIONALE

> 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.

> Conforming applications that use threads cannot call ctermid() with NULL as the parameter if either _POSIX_THREAD_SAFE_FUNCTIONS or _POSIX_THREADS is defined. If s is not NULL, the ctermid() function generates a string that, when used as a pathname, refers to the current controlling terminal for the current process. If s is NULL, the return value of ctermid() is undefined.

> There is no additional burden on the programmer-changing to use a hypothetical thread-safe version of ctermid() 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.

#### FUTURE DIRECTIONS

> None.

#### SEE ALSO

> ttyname(), the Base Definitions volume of IEEE Std 1003.1-2001, <stdio.h>

#### CHANGE HISTORY

> First released in Issue 1. Derived from Issue 1 of the SVID.

#### Issue 5

> The DESCRIPTION is updated for alignment with the POSIX Threads Extension.

#### Issue 6

> The DESCRIPTION is updated to avoid use of the term "must" for application requirements.

End of informative text.

UNIX ® is a registered Trademark of The Open Group.
POSIX ® is a registered Trademark of The IEEE.
[ Main Index | XBD | XCU | XSH | XRAT ]