From 45e13e9ddbca56faf7d0417de45767f56e2a3b35 Mon Sep 17 00:00:00 2001 From: gdr Date: Fri, 19 Sep 1997 15:47:55 +0000 Subject: [PATCH] initial checkin --- usr.man/man2/getlogin.2 | 124 +++++++++++++++++++++++ usr.man/man3/fsettext.3 | 53 ++++++++++ usr.man/man3/funopen.3 | 161 ++++++++++++++++++++++++++++++ usr.man/man5/utmp.5 | 214 ++++++++++++++++++++++++++++++++++++++++ 4 files changed, 552 insertions(+) create mode 100644 usr.man/man2/getlogin.2 create mode 100644 usr.man/man3/fsettext.3 create mode 100644 usr.man/man3/funopen.3 create mode 100644 usr.man/man5/utmp.5 diff --git a/usr.man/man2/getlogin.2 b/usr.man/man2/getlogin.2 new file mode 100644 index 0000000..4d3a0af --- /dev/null +++ b/usr.man/man2/getlogin.2 @@ -0,0 +1,124 @@ +.\" Copyright (c) 1989, 1991, 1993 +.\" The Regents of the University of California. 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. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.\" @(#)getlogin.2 8.1 (Berkeley) 6/9/93 +.\" +.TH GETLOGIN 2 "17 September 1997" GNO "System Calls" +.SH NAME +.BR getlogin , +.BR setlogin +\- get/set login name +.SH SYNOPSIS +#include +.sp 1 +char *\fBgetlogin\fR (void); +.sp 1 +int \fBsetlogin\fR (const char *\fIname\fR); +.SH DESCRIPTION +The +.BR getlogin +routine +returns the login name of the user associated with the current session, +as previously set by +.BR setlogin . +The name is normally associated with a login shell +at the time a session is created, +and is inherited by all processes descended from the login shell. +(This is true even if some of those processes assume another user ID, +for example when +.BR su (1) +is used.) +.LP +.BR Setlogin +sets the login name of the user associated with the current session to +.IR name . +This call is restricted to the super-user, and +is normally used only when a new session is being created on behalf +of the named user +(for example, at login time, or when a remote shell is invoked). +.SH RETURN VALUES +If a call to +.BR getlogin +succeeds, it returns a pointer to a null-terminated string in a static buffer. +If the name has not been set, it returns +.BR NULL . +If a call to +.BR setlogin +succeeds, a value of 0 is returned. If +.BR setlogin +fails, a value of -1 is returned and an error code is +placed in the global location +.IR errno . +.SH ERRORS +The following errors may be returned by these calls: +.RS +.IP \fBEFAULT\fR +The +.I name +parameter gave an +invalid address. +.IP \fBEINVAL\fR +The +.I name +parameter +pointed to a string that was too long. +Login names are limited to +.BR MAXLOGNAME +(from +.BR ) +characters, currently 12. +.IP \fBEPERM\fR +The caller tried to set the login name and was not the super-user. +.RE +.SH SEE ALSO +.BR setsid (2) +.SH BUGS +Login names are limited in length by +.BR setlogin . +However, lower limits are placed on login names elsewhere in the system +.RB ( UT_NAMESIZE +in +.BR ) . +.LP +In earlier versions of the system, +.BR getlogin +failed unless the process was associated with a login terminal. +The current implementation (using +.BR setlogin ) +allows getlogin to succeed even when the process has no controlling terminal. +In earlier versions of the system, the value returned by +.BR getlogin +could not be trusted without checking the user ID. +Portable programs should probably still make this check. +.SH HISTORY +The +.BR getlogin +function first appeared in 4.4BSD. diff --git a/usr.man/man3/fsettext.3 b/usr.man/man3/fsettext.3 new file mode 100644 index 0000000..23906cc --- /dev/null +++ b/usr.man/man3/fsettext.3 @@ -0,0 +1,53 @@ +.\" +.\" Macros for converting newline translation mode of stdio streams. +.\" Devin Reade, 1997 +.\" +.\" $Id: fsettext.3,v 1.1 1997/09/19 15:47:54 gdr Exp $ +.\" +.TH FSETTEXT 3 "15 September 1997" GNO "Library Routines" +.SH NAME +.BR fsettext , +.BR fsetbinary +\- set the newline translation mode for a stdio stream. +.SH SYNOPSIS +#include +.sp 1 +void \fBfsettext\fR (FILE *\fIfp\fR); +.br +void \fBfsetbinary\fR (FILE *\fIfp\fR); +.SH DESCRIPTION +The FILE struct for each stdio stream contains information as to whether +or not newline translation (carrige return to linefeed and back) will occur +for that stream. This translation mode is set when the stream is opened +by passing (or not passing) the "\fBb\fR" flag modifier to +.BR fopen (3), +.BR fdopen (3), +or +.BR freopen (3). +.LP +The stdio streams that are already open upon entry into the +.BR main +routine +.RB ( stdin , +.BR stdout , +and +.BR stderr ) +by default do newline translations. The +.BR fsetbinary +macro allows these translations to be disabled. The +.BR fsettext +macro allows these translations to be reenabled. These macros are not +necessary and should not be used for any other stream pointers. +.LP +These macros must be used before any I/O is performed on the associated +stream. If I/O has already been performed, the results are undefined. +.SH STANDARDS +.BR fsetbinary +and +.BR fsettext +are non-standard routines, and should not be used for programs intended +to be ported to other platforms. +.SH SEE ALSO +.BR fflush (3), +.BR fopen (3), +.BR stdio (3) diff --git a/usr.man/man3/funopen.3 b/usr.man/man3/funopen.3 new file mode 100644 index 0000000..6439331 --- /dev/null +++ b/usr.man/man3/funopen.3 @@ -0,0 +1,161 @@ +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek. +.\" 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. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.\" @(#)funopen.3 8.1 (Berkeley) 6/9/93 +.\" +.TH FUNOPEN 3 "17 September 1997" GNO "Library Routines" +.SH NAME +.BR funopen , +.BR fropen , +.BR fwopen +\- open a stream +.SH SYNOPSIS +#include +.sp 1 +FILE *\fBfunopen\fR (void *\fIcookie\fR, int (*\fIreadfn\fR)(void *, char *, int), int (*\fIwritefn\fR)(void *, const char *, int), fpos_t (*\fIseekfn\fR)(void *, fpos_t, int), int (*\fIclosefn\fR)(void *)); +.sp 1 +FILE *\fBfropen\fR (void *\fIcookie\fR, int (*\fIreadfn\fR)(void *, char *, int)); +.sp 1 +FILE *\fBfwopen\fR (void *\fIcookie\fR, int (*\fIwritefn\fR)(void *, char *, int)); +.SH DESCRIPTION +The +.BR funopen +function +associates a stream with up to four I/O functions. +Either +.I readfn +or +.I writefn +must be specified; +the others can be given as an appropriately-typed +.BR NULL +pointer. +These I/O +functions will be used to read, write, seek and +close the new stream. +.LP +In general, omitting a function means that any attempt to perform the +associated operation on the resulting stream will fail. +If the close function is omitted, closing the stream will flush +any buffered output and then succeed. +.LP +The calling conventions of +.IR readfn , +.IR writefn , +.I seekfn +and +.I closefn +must match those, respectively, of +.BR read (2), +.BR write (2), +.BR seek (2), +and +.BR close (2) +with the single exception that they are passed the +.I cookie +argument specified to +.BR funopen +in place of the traditional file descriptor argument. +.LP +Read and write I/O +functions are allowed to change the underlying buffer +on fully buffered or line buffered streams by calling +.BR setvbuf (3). +They are also not required to completely fill or empty the buffer. +They are not, however, allowed to change streams from unbuffered to buffered +or to change the state of the line buffering flag. +They must also be prepared to have read or write calls occur on buffers other +than the one most recently specified. +.LP +All user I/O +functions can report an error by returning \-1. +Additionally, all of the functions should set the external variable +.IR errno +appropriately if an error occurs. +.LP +An error on +.BR closefn +does not keep the stream open. +.LP +As a convenience, the include file +.BR +defines the macros +.BR fropen +and +.BR fwopen +as calls to +.BR funopen +with only a read or write function specified. +.SH RETURN VALUES +Upon successful completion, +.BR funopen +returns a +.BR FILE +pointer. +Otherwise, +.BR NULL +is returned and the global variable +.IR errno +is set to indicate the error. +.SH ERRORS +.RS +.IP \fBEINVAL\fR +The +.BR funopen +function +was called without either a read or write function. +The +.BR funopen +function +may also fail and set +.IR errno +for any of the errors +specified for the routine +.BR malloc (3). +.RE +.SH SEE ALSO +.BR fcntl (2), +.BR open (2), +.BR fclose (3), +.BR fopen (3), +.BR fseek (3), +.BR setbuf (3) +.SH HISTORY +The +.BR funopen +functions first appeared in 4.4BSD. +.SH BUGS +The +.BR funopen +function +may not be portable to systems other than BSD. diff --git a/usr.man/man5/utmp.5 b/usr.man/man5/utmp.5 new file mode 100644 index 0000000..d869f5b --- /dev/null +++ b/usr.man/man5/utmp.5 @@ -0,0 +1,214 @@ +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. 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. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.\" @(#)utmp.5 8.2 (Berkeley) 3/17/94 +.\" +.TH UTMP 5 "17 September 1997" GNO "File Formats" +.SH NAME +.BR utmp , +.BR wtmp , +.BR lastlog +\- login records +.SH SYNOPSIS +#include +.SH DESCRIPTION +The file +.BR +declares the structures used to record information about current +users in the file +.BR utmp , +logins and logouts in the file +.BR wtmp , +and last logins in the file +.BR lastlog . +The time stamps of date changes, shutdowns and reboots are also logged in +the +.BR wtmp +file. +.LP +These files can grow rapidly on busy systems, daily or weekly rotation +is recommended. +If any of these files do not exist, it is not created. +These +files must be created manually and are normally maintained in either the script +.BR /etc/daily +or the script +.BR /etc/weekly . +(See +.BR cron (8).) +.nf + +#define _PATH_UTMP "/var/run/utmp" +#define _PATH_WTMP "/var/log/wtmp" +#define _PATH_LASTLOG "/var/log/lastlog" + +#define UT_NAMESIZE 8 +#define UT_LINESIZE 8 +#define UT_HOSTSIZE 16 + +struct lastlog { + time_t ll_time; + char ll_line[UT_LINESIZE]; + char ll_host[UT_HOSTSIZE]; +}; + +struct utmp { + char ut_line[UT_LINESIZE]; + char ut_name[UT_NAMESIZE]; + char ut_host[UT_HOSTSIZE]; + long ut_time; +}; +.fi +.LP +Each time a user logs in, the +.BR login +program looks up the user's +.I UID +in the file +.BR lastlog. +If it is found, the timestamp of the last time the user logged +in, the terminal line and the hostname +are written to the standard output. (Providing the login is not +.IR quiet , +see +.BR login (1).) +The +.BR login +program then records the new login time in the file +.BR lastlog . +.LP +After the new +.I lastlog +record is written, +the file +.BR utmp +is opened and the +.I utmp +record for the user inserted. +This record remains there until +the user logs out at which time it is deleted. +The +.BR utmp +file is used by the programs +.BR rwho (1), +.BR users (1), +.BR w (1), +and +.BR who (1). +.LP +Next, the +.BR login +program opens the file +.BR wtmp , +and appends the user's +.I utmp +record. +The same +.I utmp +record, with an updated time stamp is later appended +to the file when the user logs out. (See +.BR init (8).) +The +.BR wtmp +file is used by the programs +.BR last (1) +and +.BR ac (8). +.LP +In the event of a date change, a shutdown or reboot, the +following items are logged in the +.BR wtmp +file. +.LP +.RS +.IP "\fBreboot\fR, \fBshutdown\fR" +A system reboot or shutdown has been initiated. +The character +.BR \&~ +is placed in the field +.IR ut_line , +and +.B reboot +or +.B shutdown +in the field +.IR ut_name . +(See +.BR shutdown (8) +and +.BR reboot (8).) +.LP +.IP \fBdate\fR +The system time has been manually or automatically updated. +(See +.BR date (1).) +The command name +.BR date +is recorded in the field +.IR ut_name . +In the field +.IR ut_line , +the character +.BR \\*(Ba +indicates the time prior to the change, and the character +.BR \&{ +indicates the new time. +.RE +.SH FILES +.RS +.IP \fB/var/run/utmp\fR +The +.BR utmp file. +.IP \fB/var/log/wtmp\fR +The +.BR wtmp file. +.IP \fB/var/log/lastlog\fR +The +.BR lastlog file. +.RE +.SH BUGS +This man page is not quite right for the GNO implementation (the structures +are incorrect, as is the utmp path). +.SH SEE ALSO +.BR last (1), +.BR login (1), +.BR who (1), +.BR ac (8), +.BR init (8) +.SH HISTORY +A +.BR utmp +and +.BR wtmp +file format appeared in v6. +The +.BR lastlog +file format appeared in 3.0BSD.