| ptsname.3 (120054) | ptsname.3 (181905) |
|---|---|
| 1.\" 2.\" Copyright (c) 2002 The FreeBSD Project, Inc. 3.\" All rights reserved. 4.\" 5.\" This software includes code contributed to the FreeBSD Project 6.\" by Ryan Younce of North Carolina State University. 7.\" 8.\" Redistribution and use in source and binary forms, with or without --- 15 unchanged lines hidden (view full) --- 24.\" OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 25.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED 26.\" TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR 27.\" PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF 28.\" LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 29.\" NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 30.\" SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 31.\" | 1.\" 2.\" Copyright (c) 2002 The FreeBSD Project, Inc. 3.\" All rights reserved. 4.\" 5.\" This software includes code contributed to the FreeBSD Project 6.\" by Ryan Younce of North Carolina State University. 7.\" 8.\" Redistribution and use in source and binary forms, with or without --- 15 unchanged lines hidden (view full) --- 24.\" OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 25.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED 26.\" TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR 27.\" PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF 28.\" LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 29.\" NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 30.\" SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 31.\" |
| 32.\" $FreeBSD: head/lib/libc/stdlib/grantpt.3 120054 2003-09-14 13:41:59Z ru $ | 32.\" $FreeBSD: head/lib/libc/stdlib/ptsname.3 181905 2008-08-20 08:31:58Z ed $ |
| 33.\" | 33.\" |
| 34.Dd December 23, 2002 | 34.Dd August 20, 2008 |
| 35.Os | 35.Os |
| 36.Dt GRANTPT 3 | 36.Dt PTSNAME 3 |
| 37.Sh NAME 38.Nm grantpt , 39.Nm ptsname , | 37.Sh NAME 38.Nm grantpt , 39.Nm ptsname , |
| 40.Nm unlockpt , 41.Nm posix_openpt | 40.Nm unlockpt |
| 42.Nd pseudo-terminal access functions 43.Sh LIBRARY 44.Lb libc 45.Sh SYNOPSIS 46.In stdlib.h 47.Ft int 48.Fn grantpt "int fildes" 49.Ft "char *" 50.Fn ptsname "int fildes" 51.Ft int 52.Fn unlockpt "int fildes" | 41.Nd pseudo-terminal access functions 42.Sh LIBRARY 43.Lb libc 44.Sh SYNOPSIS 45.In stdlib.h 46.Ft int 47.Fn grantpt "int fildes" 48.Ft "char *" 49.Fn ptsname "int fildes" 50.Ft int 51.Fn unlockpt "int fildes" |
| 53.In fcntl.h 54.Ft int 55.Fn posix_openpt "int mode" | |
| 56.Sh DESCRIPTION 57The 58.Fn grantpt , 59.Fn ptsname , | 52.Sh DESCRIPTION 53The 54.Fn grantpt , 55.Fn ptsname , |
| 60.Fn unlockpt , | |
| 61and | 56and |
| 62.Fn posix_openpt | 57.Fn unlockpt |
| 63functions allow access to pseudo-terminal devices. | 58functions allow access to pseudo-terminal devices. |
| 64The first three functions accept a file descriptor 65that references the master half of a pseudo-terminal pair. | 59These three functions accept a file descriptor that references the 60master half of a pseudo-terminal pair. |
| 66This file descriptor is created with | 61This file descriptor is created with |
| 67.Fn posix_openpt . | 62.Xr posix_openpt 2 . |
| 68.Pp 69The 70.Fn grantpt 71function is used to establish ownership and permissions 72of the slave device counterpart to the master device 73specified with 74.Fa fildes . 75The slave device's ownership is set to the real user ID 76of the calling process, and the permissions are set to 77user readable-writable and group writable. 78The group owner of the slave device is also set to the 79group | 63.Pp 64The 65.Fn grantpt 66function is used to establish ownership and permissions 67of the slave device counterpart to the master device 68specified with 69.Fa fildes . 70The slave device's ownership is set to the real user ID 71of the calling process, and the permissions are set to 72user readable-writable and group writable. 73The group owner of the slave device is also set to the 74group |
| 80.Dq Li tty 81if it exists on the system; otherwise, it 82is left untouched. | 75.Dq Li tty . |
| 83.Pp 84The 85.Fn ptsname 86function returns the full pathname of the slave device 87counterpart to the master device specified with 88.Fa fildes . 89This value can be used 90to subsequently open the appropriate slave after | 76.Pp 77The 78.Fn ptsname 79function returns the full pathname of the slave device 80counterpart to the master device specified with 81.Fa fildes . 82This value can be used 83to subsequently open the appropriate slave after |
| 91.Fn posix_openpt | 84.Xr posix_openpt 2 |
| 92and 93.Fn grantpt 94have been called. 95.Pp 96The 97.Fn unlockpt 98function clears the lock held on the pseudo-terminal pair 99for the master device specified with 100.Fa fildes . | 85and 86.Fn grantpt 87have been called. 88.Pp 89The 90.Fn unlockpt 91function clears the lock held on the pseudo-terminal pair 92for the master device specified with 93.Fa fildes . |
| 101.Pp 102The 103.Fn posix_openpt 104function opens the first available master pseudo-terminal 105device and returns a descriptor to it. 106The 107.Fa mode 108argument 109specifies the flags used for opening the device: 110.Bl -tag -width ".Dv O_NOCTTY" 111.It Dv O_RDWR 112Open for reading and writing. 113.It Dv O_NOCTTY 114If set, do not allow the terminal to become 115the controlling terminal for the calling process. 116.El | |
| 117.Sh RETURN VALUES 118.Rv -std grantpt unlockpt 119.Pp 120The 121.Fn ptsname 122function returns a pointer to the name 123of the slave device on success; otherwise a 124.Dv NULL | 94.Sh RETURN VALUES 95.Rv -std grantpt unlockpt 96.Pp 97The 98.Fn ptsname 99function returns a pointer to the name 100of the slave device on success; otherwise a 101.Dv NULL |
| 125pointer is returned and the global variable 126.Va errno 127is set to indicate the error. 128.Pp 129The 130.Fn posix_openpt 131function returns a file descriptor to the first 132available master pseudo-terminal device on success; 133otherwise \-1 is returned and the global variable 134.Va errno 135is set to indicate the error. | 102pointer is returned. |
| 136.Sh ERRORS 137The | 103.Sh ERRORS 104The |
| 138.Fn grantpt , 139.Fn ptsname , | 105.Fn grantpt |
| 140and 141.Fn unlockpt 142functions may fail and set 143.Va errno 144to: 145.Bl -tag -width Er | 106and 107.Fn unlockpt 108functions may fail and set 109.Va errno 110to: 111.Bl -tag -width Er |
| 112.It Bq Er EBADF 113.Fa fildes 114is not a valid open file descriptor. |
|
| 146.It Bq Er EINVAL 147.Fa fildes 148is not a master pseudo-terminal device. 149.El 150.Pp 151In addition, the 152.Fn grantpt 153function may set 154.Va errno 155to: 156.Bl -tag -width Er 157.It Bq Er EACCES 158The slave pseudo-terminal device could not be accessed. 159.El | 115.It Bq Er EINVAL 116.Fa fildes 117is not a master pseudo-terminal device. 118.El 119.Pp 120In addition, the 121.Fn grantpt 122function may set 123.Va errno 124to: 125.Bl -tag -width Er 126.It Bq Er EACCES 127The slave pseudo-terminal device could not be accessed. 128.El |
| 160.Pp 161The 162.Fn posix_openpt 163function may fail and set 164.Va errno 165to: 166.Bl -tag -width Er 167.It Bq Er EINVAL 168.Fa mode 169consists of an invalid mode bit. 170.It Bq Er EAGAIN 171The system has no available pseudo-terminal devices. 172.El 173.Pp 174The 175.Fn grantpt , 176.Fn ptsname , 177and 178.Fn unlockpt 179functions may also fail and set 180.Va errno 181for any of the errors specified for the 182.Xr fstat 2 183system call. 184.Pp 185The 186.Fn posix_openpt 187function may also fail and set 188.Va errno 189for any of the errors specified for the 190.Xr open 2 191system call. | |
| 192.Sh SEE ALSO | 129.Sh SEE ALSO |
| 193.Xr open 2 , 194.Xr pty 4 , | 130.Xr posix_openpt 2 , 131.Xr pts 4 , |
| 195.Xr tty 4 196.Sh STANDARDS 197The 198.Fn grantpt , | 132.Xr tty 4 133.Sh STANDARDS 134The 135.Fn grantpt , |
| 199.Fn ptsname , 200.Fn unlockpt , | 136.Fn ptsname |
| 201and | 137and |
| 202.Fn posix_openpt | 138.Fn unlockpt |
| 203functions conform to 204.St -p1003.1-2001 . 205.Sh HISTORY 206The 207.Fn grantpt , | 139functions conform to 140.St -p1003.1-2001 . 141.Sh HISTORY 142The 143.Fn grantpt , |
| 208.Fn ptsname , 209.Fn unlockpt , | 144.Fn ptsname |
| 210and | 145and |
| 211.Fn posix_openpt | 146.Fn unlockpt |
| 212functions appeared in 213.Fx 5.0 . 214.Sh NOTES 215The purpose of the | 147functions appeared in 148.Fx 5.0 . 149.Sh NOTES 150The purpose of the |
| 151.Fn grantpt 152and |
|
| 216.Fn unlockpt | 153.Fn unlockpt |
| 217function has no meaning in 218.Fx . 219.Pp 220The flag 221.Dv O_NOCTTY 222is included for compatibility; in | 154functions has no meaning in |
| 223.Fx , | 155.Fx , |
| 224opening a terminal does not cause it to become 225a process's controlling terminal. | 156because pseudo-terminals obtained by 157.Xr posix_openpt 2 158are created on demand. 159Because these devices are created with proper permissions in place, they 160are guaranteed to be unused by unprivileged processes. |