\" $NetBSD: ptsname.3,v 1.13 2022/01/02 03:46:40 uwe Exp $
\"
\" Copyright (c) 2004 The NetBSD Foundation, Inc.
\" All rights reserved.
\"
\" This code is derived from software contributed to The NetBSD Foundation
\" by Christos Zoulas.
\"
\" Redistribution and use in source and binary forms, with or without
\" modification, are permitted provided that the following conditions
\" are met:
\" 1. Redistributions of source code must retain the above copyright
\"    notice, this list of conditions and the following disclaimer.
\" 2. Redistributions in binary form must reproduce the above copyright
\"    notice, this list of conditions and the following disclaimer in the
\"    documentation and/or other materials provided with the distribution.
\"
\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
\" POSSIBILITY OF SUCH DAMAGE.
\"
Dd January 2, 2022
Dt PTSNAME 3
Os
Sh NAME
Nm ptsname ,
Nm ptsname_r
Nd get the pathname of the slave pseudo-terminal device
Sh LIBRARY
Lb libc
Sh SYNOPSIS
In stdlib.h
Ft char *
Fn ptsname "int masterfd"
Ft int
Fn ptsname_r "int masterfd" "char *buf" "size_t buflen"
Sh DESCRIPTION
The
Fn ptsname
function returns the pathname of the slave pseudo-terminal device
that corresponds to the master pseudo-terminal device associated with
Fa masterfd .
The
Fn ptsname
function is not reentrant or thread-safe.
Pp
The
Fn ptsname_r
function
places the pathname of the slave pseudo-terminal device that corresponds
to the master pseudo-terminal device associated with
Fa masterfd
int the
Fa buf
argument copying up to
Fa buflen
characters.
The
Fa buf
is always
Dv NUL
terminated.
Sh RETURN VALUES
If successful,
Fn ptsname
returns a pointer to a nul-terminated string containing the pathname
of the slave pseudo-terminal device.
If an error occurs
Fn ptsname
will return
Dv NULL
and
Va errno
is set to indicate the error.
Pp
If successful,
Fn ptsname_r
places a nul-terminated string containing the pathname
of the slave pseudo-terminal device
in
Fa buf
and returns
Dv 0 .
If an error occurs
Fn ptsname_r
will return
an error number indicating what went wrong.
Sh ERRORS
The
Fn ptsname
and
Fn ptsname_r
functions will fail if:
Bl -tag -width Er
It Bq Er EACCESS
the corresponding pseudo-terminal device could not be accessed.
It Bq Er EBADF
Fa masterfd
is not a valid descriptor.
It Bq Er EINVAL
Fa masterfd
is not associated with a master pseudo-terminal device.
El
Pp
In addition the
Fn ptsname_r
function
will return:
Bl -tag -width Er
It Bq Er EINVAL
the
Fa buf
argument is
Dv NULL .
It Bq Er ERANGE
the name of the pseudo-terminal is longer than
Fa bufsiz
characters plus the terminating
Dv NUL .
El
Sh NOTES
The error returns of
Fn ptsname
are a
Nx
extension.
The
Fn ptsname
function is equivalent to:
Bd -literal
       static struct ptmget pm;
       return ioctl(masterfd, TIOCPTSNAME, &pm) == -1 ? NULL : pm.sn;
Ed
Pp
Both the
Fn ptsname
and
Fn ptsname_r
functions will also return the name of the slave pseudo-terminal if a file
descriptor to the slave pseudo-terminal is passed to
Fa masterfd .
Pp
This is a convenient extension because it allows one to use the file descriptor
obtained by
Xr open 2
Pa /dev/tty
to obtain the name of the pseudo-terminal for the current process.
Sh SEE ALSO
Xr ioctl 2 ,
Xr open 2 ,
Xr grantpt 3 ,
Xr posix_openpt 3 ,
Xr unlockpt 3
Sh STANDARDS
The
Fn ptsname
function conforms to
St -p1003.1-2001 .
Its first release was in
St -xpg4.2 .

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.