1CTERMID(3P)                POSIX Programmer's Manual               CTERMID(3P)
2
3
4

PROLOG

6       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
7       implementation of this interface may differ (consult the  corresponding
8       Linux  manual page for details of Linux behavior), or the interface may
9       not be implemented on Linux.
10

NAME

12       ctermid — generate a pathname for the controlling terminal
13

SYNOPSIS

15       #include <stdio.h>
16
17       char *ctermid(char *s);
18

DESCRIPTION

20       The ctermid() function shall generate a string that,  when  used  as  a
21       pathname,  refers  to  the current controlling terminal for the current
22       process. If ctermid() returns a pathname, access to  the  file  is  not
23       guaranteed.
24
25       The  ctermid()  function  need not be thread-safe if called with a NULL
26       parameter.
27

RETURN VALUE

29       If s is a null pointer, the string shall be generated in an  area  that
30       may  be static, the address of which shall be returned. The application
31       shall not modify the string returned. The  returned  pointer  might  be
32       invalidated  or the string content might be overwritten by a subsequent
33       call to ctermid().  The returned pointer might also be  invalidated  if
34       the  calling  thread  is  terminated.  If s is not a null pointer, s is
35       assumed to point to a character array of at least L_ctermid bytes;  the
36       string  is  placed  in this array and the value of s shall be returned.
37       The symbolic constant L_ctermid is defined in <stdio.h>, and shall have
38       a value greater than 0.
39
40       The  ctermid()  function  shall  return an empty string if the pathname
41       that would refer to the controlling terminal cannot be  determined,  or
42       if the function is unsuccessful.
43

ERRORS

45       No errors are defined.
46
47       The following sections are informative.
48

EXAMPLES

50   Determining the Controlling Terminal for the Current Process
51       The following example returns a pointer to a string that identifies the
52       controlling terminal for the current process. The pathname for the ter‐
53       minal  is stored in the array pointed to by the ptr argument, which has
54       a size of L_ctermid bytes, as indicated by the term argument.
55
56
57           #include <stdio.h>
58           ...
59           char term[L_ctermid];
60           char *ptr;
61
62           ptr = ctermid(term);
63

APPLICATION USAGE

65       The difference between ctermid() and ttyname() is that  ttyname()  must
66       be  handed  a file descriptor and return a path of the terminal associ‐
67       ated with that file descriptor, while ctermid() returns a string  (such
68       as  "/dev/tty") that refers to the current controlling terminal if used
69       as a pathname.
70

RATIONALE

72       L_ctermid must be defined appropriately for a given implementation  and
73       must  be  greater  than  zero  so  that array declarations using it are
74       accepted by the compiler. The value includes the terminating null byte.
75
76       Conforming applications that use multiple threads cannot call ctermid()
77       with  NULL  as  the parameter. If s is not NULL, the ctermid() function
78       generates a string that, when used as a pathname, refers to the current
79       controlling  terminal for the current process. If s is NULL, the return
80       value of ctermid() is undefined.
81
82       There is no additional burden on the programmer—changing to use a hypo‐
83       thetical  thread-safe version of ctermid() along with allocating a buf‐
84       fer is more of a burden than merely allocating  a  buffer.  Application
85       code  should  not  assume  that  the  returned string is short, as some
86       implementations have more than two pathname components before  reaching
87       a logical device name.
88

FUTURE DIRECTIONS

90       None.
91

SEE ALSO

93       ttyname()
94
95       The Base Definitions volume of POSIX.1‐2017, <stdio.h>
96
98       Portions  of  this text are reprinted and reproduced in electronic form
99       from IEEE Std 1003.1-2017, Standard for Information Technology --  Por‐
100       table  Operating System Interface (POSIX), The Open Group Base Specifi‐
101       cations Issue 7, 2018 Edition, Copyright (C) 2018 by the  Institute  of
102       Electrical  and  Electronics Engineers, Inc and The Open Group.  In the
103       event of any discrepancy between this version and the original IEEE and
104       The  Open Group Standard, the original IEEE and The Open Group Standard
105       is the referee document. The original Standard can be  obtained  online
106       at http://www.opengroup.org/unix/online.html .
107
108       Any  typographical  or  formatting  errors that appear in this page are
109       most likely to have been introduced during the conversion of the source
110       files  to  man page format. To report such errors, see https://www.ker
111       nel.org/doc/man-pages/reporting_bugs.html .
112
113
114
115IEEE/The Open Group                  2017                          CTERMID(3P)
Impressum