d/freebsd-dev
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Finally document the interfaces found in libutil. While being here,

Browse Source 
also add the missing declaration of forkpty() to libutil.h.

Btw., the calling interface for login(3) is crude.  Some better
abstraction is needed, perhaps similar to logwtmp(3).

2.2 candidate, but i'll wait for the spelling police first. :)
This commit is contained in:
Joerg Wunsch 1996-12-29 18:30:42 +00:00
parent 1e6c86d048
commit 483f4c8371
Notes: svn2git 2020-12-20 02:59:44 +00:00 
svn path=/head/; revision=21026
7 changed files with 425 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
lib/libutil/Makefile
View File

@ -5,7 +5,8 @@ SHLIB_MAJOR= 2
SHLIB_MINOR= 1
CFLAGS+=-DLIBC_SCCS -I${.CURDIR} -I/sys
SRCS= login.c login_tty.c logout.c logwtmp.c pty.c setproctitle.c
MAN3+= setproctitle.3
MAN3+= login.3 login_tty.3 logout.3 logwtmp.3 pty.3 setproctitle.3
MLINKS+= pty.3 openpty.3 pty.3 forkpty.3
beforeinstall:
${INSTALL} -C -o ${BINOWN} -g ${BINGRP} -m 444 ${.CURDIR}/libutil.h \

4
lib/libutil/libutil.h
View File

@ -18,7 +18,7 @@
* 5. Modifications may be freely made to this file providing the above
* conditions are met.
*
* $Id$
* $Id: libutil.h,v 1.1 1996/01/01 08:27:37 peter Exp $
*/
#ifndef _LIBUTIL_H_
@ -39,6 +39,8 @@ int logout __P((char *line));
void logwtmp __P((char *line, char *name, char *host));
int openpty __P((int *amaster, int *aslave, char *name,
struct termios *termp, struct winsize *winp));
int forkpty __P((int *amaster, char *name,
struct termios *termp, struct winsize *winp));
__END_DECLS
#endif /* !_LIBUTIL_H_ */

69
lib/libutil/login.3 Normal file
View File

@ -0,0 +1,69 @@
.\"
.\" Copyright (c) 1996 Joerg Wunsch
.\"
.\" All rights reserved.
.\"
.\" 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 DEVELOPERS ``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 DEVELOPERS 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.
.\"
.\" $Id$
.\" "
.Dd December 29, 1996
.Os
.Dt LOGIN 3
.Sh NAME
.Nm login
.Nd "log a new login record to the utmp and wtmp files"
.Sh SYNOPSIS
.Fd #include <sys/types.h>
.Fd #include <utmp.h>
.Fd #include <libutil.h>
.Ft void
.Fn login "struct utmp *ut"
.Pp
Link with
.Va -lutil
on the
.Xr cc 1
command line.
.Sh DESCRIPTION
The function
.Nm login
records the
.Ar ut
entry being passed into the appropriate slot of the
.Xr utmp 5
file (according to the controlling terminal of the calling process),
and appends it to the
.Xr wtmp 5
file. The calling process must have permission to write to both files.
.Sh RETURN VALUES
None.
.Sh SEE ALSO
.Xr logout 3 ,
.Xr ttyslot 3 ,
.Xr utmp 5 ,
.Xr wtmp 5
.Sh BUGS
The interface provided by
.Nm login
is rather crude. The caller must know about the details of a
.Va struct utmp .
Some better abstraction needs to be worked out.

66
lib/libutil/login_tty.3 Normal file
View File

@ -0,0 +1,66 @@
.\"
.\" Copyright (c) 1996 Joerg Wunsch
.\"
.\" All rights reserved.
.\"
.\" 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 DEVELOPERS ``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 DEVELOPERS 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.
.\"
.\" $Id$
.\" "
.Dd December 29, 1996
.Os
.Dt LOGIN_TTY 3
.Sh NAME
.Nm login_tty
.Nd prepare a tty for a new login session
.Sh SYNOPSIS
.Fd #include <libutil.h>
.Ft int
.Fn login_tty "int fd"
.Pp
Link with
.Va -lutil
on the
.Xr cc 1
command line.
.Sh DESCRIPTION
The function
.Nm login_tty
prepares a terminal for a new login session. The filedescriptor
.Ar fd
passed to
.Nm login_tty
must be opened for reading and writing on a terminal device. It will be
made the controlling terminal for the calling process, after allocating
a new session with
.Xr setsid 2 .
This terminal device will also be made the standard input, standard output,
and standard error output of the calling process.
.Sh RETURN VALUES
.Nm Login_tty
returns -1 if it could not make the device referenced by
.Ar fd
the controlling terminal of the calling process, and 0 otherwise.
.Sh SEE ALSO
.Xr dup2 2 ,
.Xr ioctl 2 ,
.Xr setsid 2 ,
.Xr tty 4

70
lib/libutil/logout.3 Normal file
View File

@ -0,0 +1,70 @@
.\"
.\" Copyright (c) 1996 Joerg Wunsch
.\"
.\" All rights reserved.
.\"
.\" 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 DEVELOPERS ``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 DEVELOPERS 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.
.\"
.\" $Id$
.\" "
.Dd December 29, 1996
.Os
.Dt LOGOUT 3
.Sh NAME
.Nm logout
.Nd remove an entry from the utmp file
.Sh SYNOPSIS
.Fd #include <libutil.h>
.Ft int
.Fn logout "char *line"
.Pp
Link with
.Va -lutil
on the
.Xr cc 1
command line.
.Sh DESCRIPTION
The function
.Nm logout
searches the
.Xr utmp 5
file for the slot described by
.Ar line
(usually a tty name). If such a slot could be found, it will be updated
with a record where the
.Em name
and
.Em host
fields are empty, and the timestamp field is updated to the current time.
.Sh RETURN VALUES
.Nm Logout
returns 1 if the slot described by
.Ar line
has been found and updated, 0 otherwise.
.Sh SEE ALSO
.Xr login 3 ,
.Xr utmp 5 ,
.Xr wtmp 5
.Sh BUGS
The calling interface of
.Nm logout
is incosistent with that of
.Xr login 3 .

72
lib/libutil/logwtmp.3 Normal file
View File

@ -0,0 +1,72 @@
.\"
.\" Copyright (c) 1996 Joerg Wunsch
.\"
.\" All rights reserved.
.\"
.\" 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 DEVELOPERS ``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 DEVELOPERS 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.
.\"
.\" $Id$
.\" "
.Dd December 29, 1996
.Os
.Dt LOGWTMP 3
.Sh NAME
.Nm logwtmp
.Nd append a new record to the wtmp file
.Sh SYNOPSIS
.Fd #include <libutil.h>
.Ft void
.Fn logwtmp "char *line" "char *name" "char *host"
.Pp
Link with
.Va -lutil
on the
.Xr cc 1
command line.
.Sh DESCRIPTION
The function
.Nm logwtmp
tries to append a new record to the
.Xr wtmp 5
file, using the provided arguments
.Ar line ,
.Ar name ,
and
.Ar host ,
and the current time.
.Pp
If the length of the hostname string
.Ar host
is longer than what would fit into the hostname field of the
.Xr wtmp 5
file, it will first be attempted to convert it into a numerical IP
address using
.Xr gethostbyname 3 .
Failing this, the hostname will be recorded as
.Qq invalid hostname .
.Pp
The calling process must have permission to write to both files.
.Sh RETURN VALUES
None.
.Sh SEE ALSO
.Xr gethostbyname 3 ,
.Xr login 3 ,
.Xr wtmp 5

143
lib/libutil/pty.3 Normal file
View File

@ -0,0 +1,143 @@
.\"
.\" Copyright (c) 1996 Joerg Wunsch
.\"
.\" All rights reserved.
.\"
.\" 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 DEVELOPERS ``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 DEVELOPERS 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.
.\"
.\" $Id$
.\" "
.Dd December 29, 1996
.Os
.Dt PTY 3
.Sh NAME
.Nm openpty, forkpty
.Nd auxiliary functions to obtain a pseudo-terminal
.Sh SYNOPSIS
.Fd #include <sys/types.h>
.Fd #include <sys/ioctl.h>
.Fd #include <termios.h>
.Fd #include <libutil.h>
.Ft int
.Fn openpty "int *amaster" "int *aslave" "char *name" "struct termios *termp" "struct winsize *winp"
.Ft int
.Fn forkpty "int *amaster" "char *name" "struct termios *termp" "struct winsize *winp"
.Pp
Link with
.Va -lutil
on the
.Xr cc 1
command line.
.Sh DESCRIPTION
The function
.Nm openpty
attempts to obtain the next available pseudo-terminal from the system (see
.Xr pty 4 ) .
If it successfully found one, it subsequently tries to change the
ownership of the slave device to the real UID of the current process,
the group membership to the group
.Dq tty
(if such a group exists in the system), the access permissions for
reading and writing by the owner, and for writing by the group, and to
invalidate any current use of the line by calling
.Xr revoke 2 .
.Pp
If the argument
.Ar name
is not
.Dv NULL ,
.Nm openpty
copies the pathname of the slave pty to this area. The caller is
responsible to allocate the required space in this array.
.Pp
If the arguments
.Ar termp
or
.Ar winp
are not
.Dv NULL ,
.Nm openpty
initializes the termios and window size settings from the structures
these argument point to, respectively.
.Pp
Upon return, the open filedescriptors for the master and slave side
of the pty are returned in the locations pointed to by
.Ar amaster
and
.Ar aslave ,
respectively.
.Pp
.Nm Forkpty
first calls
.Xr openpty 3
to obtain the next available pseudo-terminal from the system. Upon success,
it forks off a new process. In the child process, it closes the descriptor
for the master side of the pty, and calls
.Xr login_tty 3
for the slave pty. In the parent process, it closes the descriptor for the
slave side of the pty. The arguments
.Ar amaster ,
.Ar name ,
.Ar termp ,
and
.Ar winp
have the same meaning as described for
.Nm openpty .
.Sh RETURN VALUES
.Nm Openpty
returns 0 on success, or -1 on failure.
.Pp
.Nm Forkpty
returns -1 on failure, 0 in the slave process, and the process ID of the
slave process in the parent process.
.Sh ERRORS
On failure,
.Nm openpty
will set the global variable
.Dv errno
to
.Er ENOENT .
.Pp
In addition to this,
.Nm forkpty
may set it to any value as described for
.Xr fork 2 .
.Sh SEE ALSO
.Xr chmod 2 ,
.Xr chown 2 ,
.Xr fork 2 ,
.Xr getuid 2 ,
.Xr open 2 ,
.Xr revoke 2 ,
.Xr login_tty 3 ,
.Xr termios 3 ,
.Xr pty 4 ,
.Xr group 5
.Sh BUGS
The calling process must have an effective UID of super-user in order
to perform all the intended actions. No notification will occur if
.Nm openpty
or
.Nm forkpty
failed to proceed with one of the described steps, as long as they could
at least allocate the pty at all (and create the new process in the case
of
.Nm forkpty ) .