Synopsis

struct UserGroupCredentials * getcredentials(
         struct Task * task );

Function

The function getcredentials() returns all credentials of the given
task.  The credentials include real and effective user and group IDs,
umask, login name and session ID.  If the task pointer is NULL, the
credentials of current task are returned.

Result

    A getcredentials() function returns a valid pointer to structure
    UserGroupCredentials on success and a null pointer if an error
    occurs.

ERRORS
    [EINVAL]    An illegal task pointer was specified.

Bugs

This function leave its result in an internal static object and
return a pointer to that object. Subsequent calls to this function
will modify the same object.

Synopsis

#include <grp.h>

groupent = getgrgid(gid)
   D0               D0
struct group *getgrgid(gid_t);


groupent = getgrnam(name)
   D0                A1
struct group *getgrnam(const char *);


groupent = getgrent()
   D0
struct group *getgrent(void);

setgrent()
void setgrent(void);

endgrent()
void endgrent(void);

Function

These functions operate on the group database via netinfo.device
interface. They provide a convenient unix-compatible interface to
the group unit of the netinfo.device.

The local group database is stored in the file AmiTCP:db/group, its
format is described in netinfo.device/group.  The entry returned by
each reading function is defined by the structure group found in the
include file <grp.h>:

      struct group
      {
        char   *gr_name;              \* Group name.  *\
        char   *gr_passwd;            \* Password.    *\
        gid_t   gr_gid;               \* Group ID.    *\
        char  **gr_mem;               \* Member list. *\
       };

The functions getgrnam() and getgrgid() search the group database
for the given group name pointed to by name or the group id pointed
to by gid, respectively, returning the first one encountered.
Identical group names or group gids may result in undefined
behavior.

The getgrent() function sequentially reads the group database and is
intended for programs that wish to step through the complete list of
groups.

All three routines will open the group unit of netinfo.device for
reading, if necesssary.

The setgrent() function opens the group unit of netinfo.device.  The
endgrent() function closes the group unit of netinfo.device.  It is
recommended to call endgrent() if the program won't access group
database any more.

Result

The functions getgrent(), getgrnam(), and getgrgid(), return a
pointer to the group entry if successful; if the end of database is
reached or an error occurs a null pointer is returned.  The
functions endgrent() and setgrent() have no return value.

Notes

Errors:
[ENOENT] -- the netinfo.device could not be opened.

Other netinfo.device IO errors can be retrieved by ug_GetErr().

Files:
AmiTCP:db/group     The group database file

Compatibility:
The BSD passwd database handling routines setgrfile() and
setgroupent() are fairly useless in a networked environment and they
are not implemented.

Bugs

These functions leave their results in an internal static object and
return a pointer to that object. Subsequent calls to the same
function will modify the same object. If you need re-entrant
operation, you can use directly the netinfo.device commands.

See also

`getpwnam()`_ netinfo.device/group

Synopsis

int getgroups(
         int ngroups,
         gid_t * groups );

Function

    Getgroups() gets the current group access list of the user process
    and stores it in the array gidset. The parameter gidsetlen indicates
    the number of entries that may be placed in gidset. The function
    getgroups() returns the actual number of groups returned in gidset.
    No more than NGROUPS, as defined in <libraries/usergroup.h>, will
    ever be returned.

 RESULT
    A successful call returns the number of groups in the group set.  A
    value of -1 indicates that the argument gidsetlen is smaller than
    the number of groups in the group set.

ERRORS
    [EINVAL] The argument gidsetlen is smaller than the number of
             groups in the group set.
    [EFAULT] The argument gidset specifies an invalid address.

Result

The getuid(), geteuid(), getgid(), and getegid() functions are
always successful, and no return value is reserved to indicate an
error.

Notes

Any task can call these functions

See also

setgroups() initgroups() `getgid()`_ `getegid()`_

Synopsis

struct lastlog * getlastlog(
         uid_t uid );

Function

The getlastlog() function search the lastlog database for the given
user id. There should be an lastlog entry for each user.  A lastlog
entry with ll_time being zero means that user has never logged in
this system.

The entry returned by getlastlog is defined by the structure lastlog
found in the include file <utmp.h>:

      struct lastlog {
        long  ll_time;              \* the login time *\
        uid_t ll_uid;               \* user ID *\
        char  ll_name[UT_NAMESIZE]; \* the login name *\
        char  ll_line[UT_LINESIZE]; \* the name of login device *\
        char  ll_host[UT_HOSTSIZE]; \* where the login originated *\
      };

Result

The function getlastlog() returns a pointer to the lastlog entry if
successful; if an error occurs a null pointer is returned.

Notes

Errors:
[ENOENT] -- no lastlog entry was found
[EINVAL] -- the user ID was illegal

Bugs

The getlastlog() function leaves its result in an internal static
object and return a pointer to that object.  Subsequent calls to the
same function will modify the same object.

Current implementation stores only the lastlog data of the latest
user logged in.

See also

setlastlog()

Synopsis

char * getpass(
         const char * prompt );

Function

The getpass() function displays a prompt to, and reads in a password
from "CONSOLE:".  If this device is not accessible, getpass()
displays the prompt on the standard output and reads from the
standard input.

The password may be up to _PASSWORD_LEN (currently 128) characters
in length.  Any additional characters and the terminating newline
character are discarded.

Getpass turns off character echoing while reading the password.

Result

password -  a pointer to the null terminated password

Notes

Files:
Special device "CONSOLE:"

Bugs

The getpass function leaves its result in an internal static object
and returns a pointer to that object.  Subsequent calls to getpass
will modify the same object.

The calling program should zero the password as soon as possible to
avoid leaving the cleartext password visible in the memory.

See also

`crypt()`_

Synopsis

pid_t getpgrp();

Function

    The getpgrp() function returns the process group id for the current
    process.  Currently, the process group ID is the same as the session
    ID. The 0 is valid process group ID for console session.

RESULTS
    Upon successful completion, the value of the process group ID is
    returned.  Otherwise, a value of -1 is returned and an error code is
    stored to global errno location.

ERRORS
    [ESRCH]   The calling process don't belong to any process group.

See also

setsid() exec.library/FindTask()

Synopsis

#include <pwd.h>

pw = getpwuid(uid)
D0            D0
struct passwd *getpwuid(uid_t);


pw = getpwnam(name)
D0             A1
struct passwd *getpwnam(const char *);

pw = getpwent()
D0
struct passwd *getpwent(void);

setpwent()
void setpwent(void);

endpwent()
void endpwent(void);

Function

These functions operate on the user database via netinfo.device
interface. They provide convenient unix-compatible interface to the
password unit of the netinfo.device.

The local password database is stored in the file AmiTCP:db/passwd,
its format is described in netinfo.device/passwd.  The entry
returned by each reading function is defined by the structure passwd
found in the include file <pwd.h>:

       struct passwd
       {
         char  *pw_name;         \* Username *\
         char  *pw_passwd;       \* Encrypted password *\
         pid_t  pw_uid;          \* User ID *\
         gid_t  pw_gid;          \* Group ID *\
         char  *pw_gecos;        \* Real name etc *\
         char  *pw_dir;          \* Home directory *\
         char  *pw_shell;        \* Shell *\
       };

The functions getpwnam() and getpwuid() search the password database
for the given login name or user uid, respectively, always returning
the first one encountered.

The getpwent() function sequentially reads the password database and
is intended for programs that wish to process the complete list of
users.

All three routines will open the password unit of netinfo.device for
reading, if necesssary.

The setpwent() function opens the password unit of netinfo.device.
The endpwent() function closes the password unit of netinfo.device.
It is recommended to call endpwent() if the program won't access
password database any more.

Result

The functions getpwent(), getpwnam() and getpwuid() return a valid
pointer to a passwd structure on success and a null pointer if end
of database is reached or an error occurs. The functions endpwent()
and setpwent() have no return value.

Notes

Errors:
[ENOENT] -- the netinfo.device could not be opened.

Other netinfo.device IO errors can be retrieved by ug_GetErr().

Files:
AmiTCP:db/passwd    The password database file

Compatibility:
The BSD passwd database handling routines setpwfile() and
setpassent() are fairly useless in a networked environment and they
are not implemented.

Bugs

These functions leave their results in an internal static object and
return a pointer to that object. Subsequent calls to these function
will modify the same object. If you need re-entrant operation, you
should use directly the netinfo.device.

See also

`getgrent()`_ netinfo.device/passwd

Synopsis

mode_t getumask();

Function

The getumask() routine sets the process's file mode creation mask to
numask and returns the previous value of the mask.  The 9 low-order
access permission bits of numask are used by Unix-compatible
filesystems, for examble by NFS, to turn off corresponding bits
requested in file mode.

Result

    The value of the file mode mask is returned by the call.

ERRORS
    The getumask() function is always successful.

See also

umask()

Synopsis

#include <utmp.h>

utmpent = getutent()
   D0
struct utmp *getutent(void);

setutent()
void setutent(void);

endutent()
void endutent(void);

Function

These functions operate on the utmp database.  There is an utmp
entry for each active session.  A session is started with login
command and finished with logout command.

The entry returned by each reading function is defined by the
structure utmp found in the include file <utmp.h>:

    struct utmp {
      long    ut_time;              \* the login time *\
      long    ut_sid;               \* session ID *\
      char    ut_name[UT_NAMESIZE]; \* the login name *\
      char    ut_line[UT_LINESIZE]; \* the name of login device *\
      char    ut_host[UT_HOSTSIZE]; \* where the login originated *\
    };

The getutent() function sequentially reads the utmp database and
opens it if necessary.

The setutent() function opens the utmp database.  The
endutent() function closes the utmp database.  It is
recommended to call endutent() if the program won't access
utmp database any more.

Result

getutent() returns a pointer to the utmp entry on success and NULL
at the end of the database or on error. endutent() and setutent()
have no return value.

Notes

Errors:
[ENOENT] -- no utmp entries were available.

Bugs

getutent() returns storage owned by usergroup.library. Subsequent
enumeration calls may overwrite that storage; copy entries that
must be retained.

Without security.library the implementation exposes one session
record. With security.library it reads entries from the utmp file.

Synopsis

int initgroups(
         const char * name,
         gid_t basegroup );

Function

The initgroups() function reads through the group file and sets up,
the group access list for the user specified in name. The basegid is
automatically included in the groups list.  Typically this value is
given as the group number from the password file.

Result

The initgroups() function returns -1 if the process has got no
necessary privileges, zero if the call is succesful.

Notes

AmiTCP:db/group

See also

setgroups()

Synopsis

int setgroups(
         int ngrp,
         const gid_t * groups );

Function

Setgroups() sets the group access list of the current user process
according to the array gidset. The parameter ngroups indicates the
number of entries in the array and must be no more than NGROUPS, as
defined in <libraries/usergroup.h>.

Only the super-user may set new groups. The super-user can not
set illegal groups (-1).

Result

    A 0 value is returned on success, -1 on error, with an error
    code stored in errno and available with ug_GetErr() function.

ERRORS
    [EINVAL]    An illegal group id was specified.
    [EPERM]     The caller has got no necessary privileges.
    [EFAULT]    The address specified for gidset is illegal.

Notes

Any task can call this function.

See also

getgroups() initgroups()

Synopsis

int setlastlog(
         uid_t uid,
         char * name,
         char * con,
         char * host );

Function

The setlastlog function is used to register user logging in.  Each
time a user is logging in, the function setlastlog() should be
called to register that event.

Inputs

uid     -- the uid of user logging in
name    -- the user login name
console -- the console handler name (from ug_GetConsole())
host    -- the host which the user is logging in from

Result

The setlastlog() function returns an success indicator, 0 if the
call was successful, -1 otherwise.  The error code is set if an
error occurs.

Notes

Errors:
The setlastlog() can have following error codes:
[EFAULT] -- the utmp entry cannot be accessed
[ENOMEM] -- the memory has been exhausted
[ENOENT] -- cannot access utmp database

Bugs

Current implementation stores only the lastlog data of the latest
user logged in.

See also

`getutent()`_ getlastlog()

Synopsis

pid_t setsid();

Function

    The setsid() function creates a new session when the calling
    process is not a process group leader.  The calling process
    then becomes the session leader of this session and the only
    process in the new session.

RESULTS
    Upon successful completion, the value of the new session ID is
    returned.  Otherwise, a value of -1 is returned and an error
    code is  stored to global errno location.

ERRORS
    [EPERM]   The calling process is already a session leader.

See also

getpgrp()

Synopsis

char * ug_ConsoleName(
         BPTR con,
         char * buffer,
         ULONG size );

Function

Get a unique printable identifier for the interactive filehandle.
This identifier is usually the task name of handler concatenated
with message port address.

Inputs

fh     - An interactive filehandle
buffer - Buffer to hold console identifier
size   - Number of bytes in buffer.

Result

name - If call is successful, pointer to buffer. NULL if
       error.

Bugs

May not get the proprer console name for all different console
handlers.

See also

dos.library/GetConsoleTask()

Synopsis

int ug_OnConsole();

Function

Check if the user is logged on local console.

Result

result - 1 if the user is on console,
         0 otherwise.

Bugs

Currently checking is done depending on the process window pointer.

Synopsis

mode_t umask(
         mode_t newmask );

Function

The umask() routine sets the process's file mode creation mask to
numask and returns the previous value of the mask.  The 9 low-order
access permission bits of numask are used by Unix-compatible
filesystems, for examble by NFS, to turn off corresponding bits
requested in file mode.  This clearing allows each user to restrict
the default access to his files.

The default mask value is 022 (write access for owner only).  Child
processes should inherit the mask of the calling process.

Result

    The previous value of the file mode mask is returned by the call.

ERRORS
    The umask() function is always successful.

Bugs

The usergroup id values that won't fit into UWORD are truncated.

See also

getumask()