=========
usergroup
=========

.. This document is automatically generated. Don't edit it!

`Index <index>`_

----------

======================================= ======================================= ======================================= ======================================= 
`clude <proto/usergroup.h>

S_LH2(int, initgroups,`_`getcredentials()`_                     `getgroups()`_                          `getlastlog()`_                         
`getpass()`_                            `getpgrp()`_                            `getumask()`_                           `setgroups()`_                          
`setlastlog()`_                         `setsid()`_                             `ug_ConsoleName()`_                     `ug_OnConsole()`_                       
`umask()`_                              
======================================= ======================================= ======================================= ======================================= 

-----------

clude <proto/usergroup.h>

S_LH2(int, initgroups,
=================================================

Synopsis
~~~~~~~~
::

     AROS_LHA(const char *, name, A1),
     AROS_LHA(gid_t, basegroup, D0),
     struct UserGroupBase *, UserGroupBase, 18, Usergroup)


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.

  FILES
      AmiTCP:db/group

  SEE ALSO
      setgroups()

  HISTORY
      The initgroups function appeared in 4.2BSD.



----------

getcredentials()
================

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.



----------

getgroups()
===========

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()`_ 

----------

getlastlog()
============

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 *\
           };

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

 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()`_ 

----------

getpass()
=========

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 error 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

 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()`_ 

----------

getpgrp()
=========

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() <./exec#findtask>`_ 

----------

getumask()
==========

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()`_ 

----------

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()`_ 

----------

setlastlog()
============

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

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

 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.

 FILES



See also
~~~~~~~~

`getutent()`_ `getlastlog()`_ 

----------

setsid()
========

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()`_ 

----------

ug_ConsoleName()
================

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() <./dos#getconsoletask>`_ 

----------

ug_OnConsole()
==============

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.



----------

umask()
=======

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()`_ 

