| Qore Programming Language Reference Manual 1.0.8

Functions
UNIX User and Group Functions

## Functions
*hash | Qore::getgrgid (softint gid)
| Returns a group information hash representing the group information for the group ID passed, or, if the group ID does not exist NOTHING is returned. More...
hash | Qore::getgrgid2 (softint gid)
| Returns a group information hash representing the group information for the group ID passed, or, if the group ID does not exist, a `GETGRGID2-ERROR` exception is thrown. More...
*hash | Qore::getgrnam (string name)
| Returns a group information hash representing the group information for the group name passed, or, if the group does not exist NOTHING is returned. More...
hash | Qore::getgrnam2 (string name)
| Returns a group information hash representing the group information for the group name passed, or, if the group does not exist, a `GETGRNAM2-ERROR` exception is thrown. More...
hash | Qore::getpwnam (string name)
| Returns a password information hash representing the user information for the user name passed, or, if the user does not exist NOTHING is returned. More...
hash | Qore::getpwnam2 (string name)
| Returns a password information hash representing the user information for the user name passed, or, if the user does not exist, a `GETPWNAM2-ERROR` exception is thrown. More...
nothing | Qore::getpwuid ()
| This function variant does nothing at all; it is only included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments. More...
*hash | Qore::getpwuid (softint uid)
| Returns a password information hash representing the user information for the user ID passed, or, if the user ID does not exist NOTHING is returned. More...
hash | Qore::getpwuid2 (softint uid)
| Returns a password information hash representing the user information for the user ID passed, or, if the user ID does not exist, a `GETPWUID2-ERROR` exception is thrown. More...

## Detailed Description

UNIX user and group functions

# Group Information Hash

Key | Type | Description
`gr_name` | string | The name of the group
`gr_passwd` | string | The encrypted password for the group
`gr_gid` | int | The group id
`gr_mem` | list | List of strings giving the usernames of members of the group

# Password Information Hash

Key | Type | Description
`pw_name` | string | The username of the user
`pw_passwd` | string | The encrypted password for the user
`pw_gecos` | string | The real name or description of the user
`pw_dir` | string | The user's home directory
`pw_shell` | string | The user's login shell
`pw_uid` | int | The user's userid
`pw_gid` | int | The group id of the user's primary group

## Function Documentation

## ◆ getgrgid()

*hash Qore::getgrgid | ( | softint | gid | ) |

Returns a group information hash representing the group information for the group ID passed, or, if the group ID does not exist NOTHING is returned.

Platform Availability:
  Qore::Option::HAVE_UNIX_USERMGT

Restrictions:
  Qore::PO_NO_EXTERNAL_INFO

Code Flags:
  CONSTANT

Parameters

  gid | the group ID to look up

Returns
  a group information hash representing the group information for the group ID passed, or, if the group ID does not exist NOTHING is returned

Example:
  *hash hash = getgrgid(0);

See also
  getgrgid2() for a similar function that throws an exception if the group ID is invalid

## ◆ getgrgid2()

hash Qore::getgrgid2 | ( | softint | gid | ) |

Returns a group information hash representing the group information for the group ID passed, or, if the group ID does not exist, a `GETGRGID2-ERROR` exception is thrown.

Platform Availability:
  Qore::Option::HAVE_UNIX_USERMGT

Restrictions:
  Qore::PO_NO_EXTERNAL_INFO

Code Flags:
  RET_VALUE_ONLY

Parameters

  gid | the group ID to look up

Returns
  a group information hash representing the group information for the group ID passed, or, if the group ID does not exist, a `GETGRGID2-ERROR` exception is thrown

Example:
  *hash hash = getgrgid2(0);

Exceptions

  GETGRGID2-ERROR | invalid gid or error reading group information

See also
  getgrgid() for a similar function that does not throw an exception if the group ID is invalid

## ◆ getgrnam()

*hash Qore::getgrnam | ( | string | name | ) |

Returns a group information hash representing the group information for the group name passed, or, if the group does not exist NOTHING is returned.

Platform Availability:
  Qore::Option::HAVE_UNIX_USERMGT

Restrictions:
  Qore::PO_NO_EXTERNAL_INFO

Code Flags:
  CONSTANT

Parameters

  name | the group name to look up

Returns
  a group information hash representing the group information for the group name passed, or, if the group does not exist NOTHING is returned

Example:
  *hash hash = getgrnam("root");

See also
  getgrnam2() for a similar function that throws an exception if the group is invalid

## ◆ getgrnam2()

hash Qore::getgrnam2 | ( | string | name | ) |

Returns a group information hash representing the group information for the group name passed, or, if the group does not exist, a `GETGRNAM2-ERROR` exception is thrown.

Platform Availability:
  Qore::Option::HAVE_UNIX_USERMGT

Restrictions:
  Qore::PO_NO_EXTERNAL_INFO

Code Flags:
  RET_VALUE_ONLY

Parameters

  name | the group name to look up

Returns
  a group information hash representing the group information for the group name passed, or, if the group does not exist, a `GETGRNAM2-ERROR` exception is thrown

Example:
  *hash hash = getgrnam2("root");

Exceptions

  GETGRNAM2-ERROR | invalid group or error reading group information

See also
  getgrnam() for a similar function that does not throw an exception if the group is invalid

## ◆ getpwnam()

hash Qore::getpwnam | ( | string | name | ) |

Returns a password information hash representing the user information for the user name passed, or, if the user does not exist NOTHING is returned.

Platform Availability:
  Qore::Option::HAVE_UNIX_USERMGT

Restrictions:
  Qore::PO_NO_EXTERNAL_INFO

Code Flags:
  CONSTANT

Parameters

  name | the user name to look up

Returns
  a password information hash representing the user information for the user name passed, or, if the user does not exist NOTHING is returned

Example:
  *hash hash = getpwnam("root");

See also
  getpwnam2() for a similar function that throws an exception if the user is invalid

## ◆ getpwnam2()

hash Qore::getpwnam2 | ( | string | name | ) |

Returns a password information hash representing the user information for the user name passed, or, if the user does not exist, a `GETPWNAM2-ERROR` exception is thrown.

Platform Availability:
  Qore::Option::HAVE_UNIX_USERMGT

Restrictions:
  Qore::PO_NO_EXTERNAL_INFO

Code Flags:
  RET_VALUE_ONLY

Parameters

  name | the user name to look up

Returns
  a password information hash representing the user information for the user name passed, or, if the user does not exist, a `GETPWNAM2-ERROR` exception is thrown

Example:
  *hash hash = getpwnam2("root");

Exceptions

  GETPWNAM2-ERROR | invalid user or error reading user information

See also
  getpwnam() for a similar function that does not throw an exception if the user is invalid

## ◆ getpwuid() [1/2]

nothing Qore::getpwuid | ( |  | ) |

This function variant does nothing at all; it is only included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments.

Restrictions:
  Qore::PO_NO_EXTERNAL_INFO

Code Flags:
  RUNTIME_NOOP

## ◆ getpwuid() [2/2]

*hash Qore::getpwuid | ( | softint | uid | ) |

Returns a password information hash representing the user information for the user ID passed, or, if the user ID does not exist NOTHING is returned.

Platform Availability:
  Qore::Option::HAVE_UNIX_USERMGT

Restrictions:
  Qore::PO_NO_EXTERNAL_INFO

Code Flags:
  CONSTANT

Parameters

  uid | the user ID to look up

Returns
  a password information hash representing the user information for the user ID passed, or, if the user ID does not exist NOTHING is returned

Example:
  *hash hash = getpwuid(0);

See also
  getpwuid2() for a similar function that throws an exception if the user ID is invalid

## ◆ getpwuid2()

hash Qore::getpwuid2 | ( | softint | uid | ) |

Returns a password information hash representing the user information for the user ID passed, or, if the user ID does not exist, a `GETPWUID2-ERROR` exception is thrown.

Platform Availability:
  Qore::Option::HAVE_UNIX_USERMGT

Restrictions:
  Qore::PO_NO_EXTERNAL_INFO

Code Flags:
  RET_VALUE_ONLY

Parameters

  uid | the user ID to look up

Returns
  a password information hash representing the user information for the user ID passed, or, if the user ID does not exist, a `GETPWUID2-ERROR` exception is thrown

Example:
  *hash hash = getpwuid2(0);

Exceptions

  GETPWUID2-ERROR | invalid uid or error reading user information

See also
  getpwuid() for a similar function that does not throw an exception if the user ID is invalid