Differential D42470 Diff 171465 lib/libc/stdlib/ptsname.3

Changeset View

Standalone View

lib/libc/stdlib/ptsname.3

	Show All 23 Lines
	.\" OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,			.\" OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
	.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED			.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
	.\" TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR			.\" TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
	.\" PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF			.\" PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
	.\" LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING			.\" LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
	.\" NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS			.\" NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
	.\" SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.			.\" SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
	.\"			.\"
	.Dd October 14, 2023			.Dd February 15, 2026
	.Dt PTSNAME 3			.Dt PTSNAME 3
	.Os			.Os
	.Sh NAME			.Sh NAME
	.Nm grantpt ,			.Nm grantpt ,
	.Nm ptsname ,			.Nm ptsname ,
	.Nm ptsname_r ,			.Nm ptsname_r ,
	.Nm unlockpt			.Nm unlockpt
	.Nd pseudo-terminal access functions			.Nd pseudo-terminal access functions
	▲ Show 20 Lines • Show All 70 Lines • ▼ Show 20 Lines
	function returns a pointer to the name			function returns a pointer to the name
	of the slave device on success; otherwise a			of the slave device on success; otherwise a
	.Dv NULL			.Dv NULL
	pointer is returned.			pointer is returned.
	.Pp			.Pp
	The			The
	.Fn ptsname_r			.Fn ptsname_r
	function returns the value 0 if successful;			function returns the value 0 if successful;
	otherwise a nonzero value is returned and the global variable			otherwise an error number is returned to indicate the error.
				.Pp
				As a
				.Fx
				extension, the global variable
	.Va errno			.Va errno
	is set to indicate the error.			is also set to indicate the error for convenience,
	Note:			even though
				.St -p1003.1-2024
				only requires the error number to be returned.
				.Pp
				When compiled without POSIX.1-2024 visibility,
	.Fn ptsname_r			.Fn ptsname_r
	was previously documented as returning -1 on error.			uses the legacy FreeBSD ABI and returns -1 on error while setting
	In the future it will be changed to return an error number, for POSIX			.Va errno .
	compatibility.
	Therefore, callers should not check for -1.
	.Sh ERRORS			.Sh ERRORS
	The			The
	.Fn grantpt ,			.Fn grantpt ,
	.Fn ptsname ,			.Fn ptsname ,
	.Fn ptsname_r			.Fn ptsname_r
	and			and
	.Fn unlockpt			.Fn unlockpt
	functions may fail and set			functions may fail and set
	.Va errno			.Va errno
	to:			to:
	.Bl -tag -width Er			.Bl -tag -width Er
	.It Bq Er EBADF			.It Bq Er EBADF
	.Fa fildes			.Fa fildes
	is not a valid open file descriptor.			is not a valid open file descriptor.
	.It Bq Er EINVAL			.It Bq Er EINVAL
	.Fa fildes			.Fa fildes
	is not a master pseudo-terminal device.			is not a master pseudo-terminal device,
				or
				.Po
				for
				.Fn ptsname_r
				.Pc
				.Fa buffer
				is a null pointer.
	.El			.El
	.Pp			.Pp
	In addition, the			In addition, the
	.Fn ptsname_r			.Fn ptsname_r
	function may set			function may set
	.Va errno			.Va errno
	to:			to:
	.Bl -tag -width Er			.Bl -tag -width Er
	Show All 15 Lines
	.Xr pts 4 ,			.Xr pts 4 ,
	.Xr tty 4			.Xr tty 4
	.Sh STANDARDS			.Sh STANDARDS
	The			The
	.Fn ptsname			.Fn ptsname
	function conforms to			function conforms to
	.St -p1003.1-2008 .			.St -p1003.1-2008 .
	.Pp			.Pp
				The
				.Fn ptsname_r
				function conforms to
				.St -p1003.1-2024 ,
				except that
				.Fx
				also sets
				.Va errno
				as an extension.
				.Pp
	This implementation of			This implementation of
	.Fn grantpt			.Fn grantpt
	and			and
	.Fn unlockpt			.Fn unlockpt
	does not conform to			does not conform to
	.St -p1003.1-2008 ,			.St -p1003.1-2008 ,
	because it depends on			because it depends on
	.Xr posix_openpt 2			.Xr posix_openpt 2
	to create the pseudo-terminal device with proper permissions in place.			to create the pseudo-terminal device with proper permissions in place.
	It only validates whether			It only validates whether
	.Fa fildes			.Fa fildes
	is a valid pseudo-terminal master device.			is a valid pseudo-terminal master device.
	Future revisions of the specification will likely allow this behaviour,			Future revisions of the specification will likely allow this behaviour,
	as stated by the Austin Group.			as stated by the Austin Group.
	.Sh HISTORY			.Sh HISTORY
	The			The
	.Fn grantpt ,			.Fn grantpt ,
	.Fn ptsname			.Fn ptsname
	and			and
	.Fn unlockpt			.Fn unlockpt
	functions appeared in			functions appeared in
	.Fx 5.0 .			.Fx 5.0 .
				.Pp
				The
				.Fn ptsname_r
				function appeared in
				.Fx 13.0 .
				In
				.Fx 16.0 ,
				the function was changed to return the error number directly
				to conform with
				.St -p1003.1-2024 ,
				while maintaining binary compatibility with earlier versions.