KCoreAddons

kuser.h
1 /*
2  KUser - represent a user/account
3 
4  SPDX-FileCopyrightText: 2002-2003 Tim Jansen <[email protected]>
5  SPDX-FileCopyrightText: 2003 Oswald Buddenhagen <[email protected]>
6  SPDX-FileCopyrightText: 2004 Jan Schaefer <[email protected]>
7  SPDX-FileCopyrightText: 2014 Alex Richardson <[email protected]>
8 
9  SPDX-License-Identifier: LGPL-2.0-or-later
10 */
11 #ifndef KUSER_H
12 #define KUSER_H
13 
14 #include <kcoreaddons_export.h>
15 
16 #include <QSharedDataPointer>
17 #include <QStringList>
18 #include <QVariant>
19 #include <qcontainerfwd.h>
20 
21 class KUserGroup;
22 class QString;
23 
24 #ifdef Q_OS_WIN
25 typedef void *K_UID;
26 typedef void *K_GID;
27 struct WindowsSIDWrapper;
28 #else
29 #include <sys/types.h>
30 typedef uid_t K_UID;
31 typedef gid_t K_GID;
32 struct passwd;
33 struct group;
34 #endif
35 
36 // The following is to avoid compile errors using msvc, and it is done
37 // using a common #define to avoid helpful people accidentally cleaning this
38 // not quite pretty thing and breaking it for people on windows.
39 // See https://git.reviewboard.kde.org/r/127598/ for details
40 #define KCOREADDONS_UINT_MAX (std::numeric_limits<uint>::max)()
41 
42 /** A platform independent user or group ID.
43  *
44  *
45  * This struct is required since Windows does not have an integer uid_t/gid_t type
46  * but instead uses an opaque binary blob (SID) which must free allocated memory.
47  * On UNIX this is simply a uid_t/gid_t and all operations are inline, so there is
48  * no runtime overhead over using the uid_t/gid_t directly. On Windows this is an implicitly
49  * shared class that frees the underlying SID once no more references remain.
50  *
51  * Unlike KUser/KUserGroup this does not query additional information, it is simply
52  * an abstraction over the native user/group ID type. If more information is necessary, a
53  * KUser or KUserGroup instance can be constructed from this ID
54  *
55  * @internal
56  * @author Alex Richardson <[email protected]>
57  */
58 template<typename T>
59 struct KCOREADDONS_EXPORT KUserOrGroupId {
60  typedef T NativeType;
61 
62 protected:
63  /** Creates an invalid KUserOrGroupId */
65  /** Creates a KUserOrGroupId from a native user/group ID. On windows this will not take
66  * ownership over the passed SID, a copy will be created instead.
67  */
68  explicit KUserOrGroupId(NativeType nativeId);
69  /** Copy constructor. This is very fast, objects can be passed by value */
70  KUserOrGroupId(const KUserOrGroupId<T> &other);
71  KUserOrGroupId &operator=(const KUserOrGroupId<T> &other);
72  ~KUserOrGroupId();
73 
74 public:
75  /** @return true if this object references a valid user/group ID.
76  * @note If this returns true it doesn't necessarily mean that the referenced user/group exists,
77  * it only checks whether this value could be a valid user/group ID.
78  */
79  bool isValid() const;
80  /**
81  * @return A user/group ID that can be used in operating system specific functions
82  * @note On Windows the returned pointer will be freed once the last KUserOrGroupId referencing
83  * this user/group ID is deleted. Make sure that the KUserOrGroupId object remains valid as
84  * long as the native pointer is needed.
85  */
86  NativeType nativeId() const;
87  /** @return A string representation of this user ID, not the name of the user
88  * On UNIX this is a simple integer, e.g. "0" for root. On Windows this is a string
89  * like e.g. "S-1-5-32-544" for the Administrators group
90  */
91  QString toString() const;
92  /** @return whether this KUserOrGroupId is equal to @p other */
93  bool operator==(const KUserOrGroupId &other) const;
94  /** @return whether this KUserOrGroupId is not equal to @p other */
95  bool operator!=(const KUserOrGroupId &other) const;
96 
97 private:
98 #ifdef Q_OS_WIN
100 #else
101  NativeType id;
102 #endif
103 };
104 
105 #ifdef Q_OS_WIN
106 template<>
108 template<>
110 template<>
111 KUserOrGroupId<void *>::KUserOrGroupId(KUserOrGroupId::NativeType nativeId);
112 template<>
114 template<>
116 template<>
118 template<>
119 KUserOrGroupId<void *>::NativeType KUserOrGroupId<void *>::nativeId() const;
120 template<>
122 template<>
123 bool KUserOrGroupId<void *>::operator==(const KUserOrGroupId &other) const;
124 template<>
125 bool KUserOrGroupId<void *>::operator!=(const KUserOrGroupId &other) const;
126 #endif
127 
128 /** A platform independent user ID.
129  * @see KUserOrGroupId
130  * @since 5.0
131  * @author Alex Richardson <[email protected]>
132  */
133 struct KCOREADDONS_EXPORT KUserId : public KUserOrGroupId<K_UID> {
134  /** Creates an invalid KUserId */
136  {
137  }
138  /** Creates an KUserId from the native user ID type */
139  explicit KUserId(K_UID uid)
140  : KUserOrGroupId(uid)
141  {
142  }
143  KUserId(const KUserId &other)
144  : KUserOrGroupId(other)
145  {
146  }
147  ~KUserId()
148  {
149  }
150  /** @return a KUserId for the user with name @p name, or an invalid KUserId if no
151  * user with this name was found on the system
152  */
153  static KUserId fromName(const QString &name);
154  /** @return a KUserId for the current user. This is like ::getuid() on UNIX. */
155  static KUserId currentUserId();
156  /** @return a KUserId for the current effective user. This is like ::geteuid() on UNIX.
157  * @note Windows does not have setuid binaries, so on Windows this will always be the same
158  * as KUserId::currentUserId()
159  */
160  static KUserId currentEffectiveUserId();
161 };
162 
163 /** A platform independent group ID.
164  * @see KUserOrGroupId
165  * @since 5.0
166  * @author Alex Richardson <[email protected]>
167  */
168 struct KCOREADDONS_EXPORT KGroupId : public KUserOrGroupId<K_GID> {
169  /** Creates an invalid KGroupId */
171  {
172  }
173  /** Creates an KGroupId from the native group ID type */
174  explicit KGroupId(K_GID gid)
175  : KUserOrGroupId(gid)
176  {
177  }
178  KGroupId(const KGroupId &other)
179  : KUserOrGroupId(other)
180  {
181  }
182  ~KGroupId()
183  {
184  }
185  /** @return A KGroupId for the user with name @p name, or an invalid KGroupId if no
186  * user with this name was found on the system
187  */
188  static KGroupId fromName(const QString &name);
189  /** @return a KGroupId for the current user. This is like ::getgid() on UNIX. */
190  static KGroupId currentGroupId();
191  /** @return a KGroupId for the current effective user. This is like ::getegid() on UNIX.
192  * @note Windows does not have setuid binaries, so on Windows this will always be the same
193  * as KGroupId::currentGroupId()
194  */
195  static KGroupId currentEffectiveGroupId();
196 };
197 
198 #ifndef Q_OS_WIN
199 inline uint qHash(const KUserId &id, uint seed = 0)
200 {
201  return qHash(id.nativeId(), seed);
202 }
203 inline uint qHash(const KGroupId &id, uint seed = 0)
204 {
205  return qHash(id.nativeId(), seed);
206 }
207 #else
208 // can't be inline on windows, because we would need to include windows.h (which can break code)
209 KCOREADDONS_EXPORT uint qHash(const KUserId &id, uint seed = 0);
210 KCOREADDONS_EXPORT uint qHash(const KGroupId &id, uint seed = 0);
211 #endif
212 
213 /**
214  * \class KUser kuser.h <KUser>
215  *
216  * @short Represents a user on your system
217  *
218  * This class represents a user on your system. You can either get
219  * information about the current user, of fetch information about
220  * a user on the system. Instances of this class will be explicitly shared,
221  * so copying objects is very cheap and you can safely pass objects by value.
222  *
223  * @author Tim Jansen <[email protected]>
224  */
225 class KCOREADDONS_EXPORT KUser
226 {
227 public:
228  enum UIDMode {
229  UseEffectiveUID, ///< Use the effective user id.
230  UseRealUserID, ///< Use the real user id.
231  };
232 
233  /**
234  * Creates an object that contains information about the current user.
235  * (as returned by getuid(2) or geteuid(2), taking $LOGNAME/$USER into
236  * account).
237  * @param mode if #UseEffectiveUID is passed the effective
238  * user is returned.
239  * If #UseRealUserID is passed the real user will be
240  * returned.
241  * The real UID will be different than the effective UID in setuid
242  * programs; in
243  * such a case use the effective UID for checking permissions, and
244  * the real UID for displaying information about the user.
245  */
246  explicit KUser(UIDMode mode = UseEffectiveUID);
247 
248  /**
249  * Creates an object for the user with the given user id.
250  * If the user does not exist isValid() will return false.
251  * @param uid the user id
252  */
253  explicit KUser(K_UID uid);
254 
255  /**
256  * Creates an object for the user with the given user id.
257  * If the KUserId object is invalid this one will be, too.
258  * @param uid the user id
259  */
260  explicit KUser(KUserId uid);
261 
262  /**
263  * Creates an object that contains information about the user with the given
264  * name. If the user does not exist isValid() will return false.
265  *
266  * @param name the name of the user
267  */
268  explicit KUser(const QString &name);
269 
270  /**
271  * Creates an object that contains information about the user with the given
272  * name. If the user does not exist isValid() will return false.
273  *
274  * @param name the name of the user
275  */
276  explicit KUser(const char *name);
277 
278 #ifndef Q_OS_WIN
279  /**
280  * Creates an object from a passwd structure.
281  * If the pointer is null isValid() will return false.
282  *
283  * @param p the passwd structure to create the user from
284  */
285  explicit KUser(const passwd *p);
286 #endif
287 
288  /**
289  * Creates an object from another KUser object
290  * @param user the user to create the new object from
291  */
292  KUser(const KUser &user);
293 
294  /**
295  * Copies a user
296  * @param user the user to copy
297  * @return this object
298  */
299  KUser &operator=(const KUser &user);
300 
301  /**
302  * Two KUser objects are equal if the userId() are identical.
303  * Invalid users never compare equal.
304  */
305  bool operator==(const KUser &user) const;
306 
307  /**
308  * Two KUser objects are not equal if userId() are not identical.
309  * Invalid users always compare unequal.
310  */
311  bool operator!=(const KUser &user) const;
312 
313  /**
314  * Returns true if the user is valid. A KUser object can be invalid if
315  * you created it with an non-existing uid or name.
316  * @return true if the user is valid
317  */
318  bool isValid() const;
319 
320  /** @return the native user id of the user. */
321  KUserId userId() const;
322 
323  /** @return the native user id of the user. */
324  KGroupId groupId() const;
325 
326 #if KCOREADDONS_ENABLE_DEPRECATED_SINCE(5, 0)
327  /**
328  * Returns the group id of the user.
329  * @return the id of the group or -1 if user is invalid
330  * @deprecated since 5.0 use KUser::groupId()
331  */
332  KCOREADDONS_DEPRECATED_VERSION(5, 0, "Use KUser::groupId()")
333  K_GID gid() const
334  {
335  return groupId().nativeId();
336  }
337 #endif
338 
339  /**
340  * Checks whether the user is the super user (root).
341  * @return true if the user is root
342  */
343  bool isSuperUser() const;
344 
345  /**
346  * The login name of the user.
347  * @return the login name of the user or QString() if user is invalid
348  */
349  QString loginName() const;
350 
351 #if KCOREADDONS_ENABLE_DEPRECATED_SINCE(5, 0)
352  /**
353  * The full name of the user.
354  * @return the full name of the user or QString() if user is invalid
355  * @deprecated Since 5.0, use property(KUser::FullName) instead
356  */
357  KCOREADDONS_DEPRECATED_VERSION(5, 0, "Use KUser::property(KUser::FullName).toString()")
358  QString fullName() const
359  {
360  return property(FullName).toString();
361  }
362  /**
363  * Returns the user id of the user.
364  * @return the id of the user or -1 (UNIX)/ null(Windows) if user is invalid
365  * @deprecated since 5.0 use KUser::userId()
366  */
367  KCOREADDONS_DEPRECATED_VERSION(5, 0, "Use KUser::userId().nativeId()")
368  K_UID uid() const
369  {
370  return userId().nativeId();
371  }
372 #endif
373 
374  /**
375  * The path to the user's home directory.
376  * @return the home directory of the user or QString() if the
377  * user is invalid
378  */
379  QString homeDir() const;
380 
381  /**
382  * The path to the user's face file.
383  * @return the path to the user's face file or QString() if no
384  * face has been set
385  */
386  QString faceIconPath() const;
387 
388  /**
389  * The path to the user's login shell.
390  * @return the login shell of the user or QString() if the
391  * user is invalid
392  */
393  QString shell() const;
394 
395  /**
396  * @param maxCount the maximum number of groups to return
397  * @return all groups of the user
398  */
399  QList<KUserGroup> groups(uint maxCount = KCOREADDONS_UINT_MAX) const;
400 
401  /**
402  * @param maxCount the maximum number of groups to return
403  * @return all group names of the user
404  */
405  QStringList groupNames(uint maxCount = KCOREADDONS_UINT_MAX) const;
406 
407  enum UserProperty {
408  FullName,
409  RoomNumber,
410  WorkPhone,
411  HomePhone,
412  };
413 
414  /**
415  * Returns an extended property.
416  *
417  * Under Windows, @p RoomNumber, @p WorkPhone and @p HomePhone are unsupported.
418  *
419  * @return a QVariant with the value of the property or an invalid QVariant,
420  * if the property is not set
421  */
422  QVariant property(UserProperty which) const;
423 
424  /**
425  * Destructor.
426  */
427  ~KUser();
428 
429  /**
430  * @param maxCount the maximum number of users to return
431  * @return all users of the system.
432  */
433  static QList<KUser> allUsers(uint maxCount = KCOREADDONS_UINT_MAX);
434 
435  /**
436  * @param maxCount the maximum number of users to return
437  * @return all user names of the system.
438  */
439  static QStringList allUserNames(uint maxCount = KCOREADDONS_UINT_MAX);
440 
441 private:
443 };
444 
445 /**
446  * \class KUserGroup kuser.h <KUserGroup>
447  *
448  * @short Represents a group on your system
449  *
450  * This class represents a group on your system. You can either get
451  * information about the group of the current user, of fetch information about
452  * a group on the system. Instances of this class will be explicitly shared,
453  * so copying objects is very cheap and you can safely pass objects by value.
454  *
455  * @author Jan Schaefer <[email protected]>
456  */
457 class KCOREADDONS_EXPORT KUserGroup
458 {
459 public:
460  /**
461  * Create an object from a group name.
462  * If the group does not exist, isValid() will return false.
463  * @param name the name of the group
464  */
465  explicit KUserGroup(const QString &name);
466 
467  /**
468  * Create an object from a group name.
469  * If the group does not exist, isValid() will return false.
470  * @param name the name of the group
471  */
472  explicit KUserGroup(const char *name);
473 
474  /**
475  * Creates an object for the group with the given group id.
476  * If the KGroupId object is invalid this one will be, too.
477  * @param gid the group id
478  */
479  explicit KUserGroup(KGroupId gid);
480 
481  /**
482  * Create an object from the group of the current user.
483  * @param mode if #KUser::UseEffectiveUID is passed the effective user
484  * will be used. If #KUser::UseRealUserID is passed the real user
485  * will be used.
486  * The real UID will be different than the effective UID in setuid
487  * programs; in such a case use the effective UID for checking
488  * permissions, and the real UID for displaying information about
489  * the group associated with the user.
490  */
492 
493  /**
494  * Create an object from a group id.
495  * If the group does not exist, isValid() will return false.
496  * @param gid the group id
497  */
498  explicit KUserGroup(K_GID gid);
499 
500 #ifndef Q_OS_WIN
501  /**
502  * Creates an object from a group structure.
503  * If the pointer is null, isValid() will return false.
504  * @param g the group structure to create the group from.
505  */
506  explicit KUserGroup(const group *g);
507 #endif
508 
509  /**
510  * Creates a new KUserGroup instance from another KUserGroup object
511  * @param group the KUserGroup to copy
512  */
513  KUserGroup(const KUserGroup &group);
514 
515  /**
516  * Copies a group
517  * @param group the group that should be copied
518  * @return this group
519  */
520  KUserGroup &operator=(const KUserGroup &group);
521 
522  /**
523  * Two KUserGroup objects are equal if their gid()s are identical.
524  * Invalid groups never compare equal.
525  * @return true if the groups are identical
526  */
527  bool operator==(const KUserGroup &group) const;
528 
529  /**
530  * Two KUserGroup objects are not equal if their gid()s are not identical.
531  * Invalid groups always compare unequal.
532  * @return true if the groups are not identical
533  */
534  bool operator!=(const KUserGroup &group) const;
535 
536  /**
537  * Returns whether the group is valid.
538  * A KUserGroup object can be invalid if it is
539  * created with a non-existing gid or name.
540  * @return true if the group is valid
541  */
542  bool isValid() const;
543 
544 #if KCOREADDONS_ENABLE_DEPRECATED_SINCE(5, 0)
545  /**
546  * Returns the group id of the group.
547  * @return the group id of the group or -1 if the group is invalid
548  * @deprecated since 5.0 use KUserGroup::groupId()
549  */
550  KCOREADDONS_DEPRECATED_VERSION(5, 0, "Use KUserGroup::groupId().nativeId()")
551  K_GID gid() const
552  {
553  return groupId().nativeId();
554  }
555 #endif
556 
557  /** @return the native group id of the user. */
558  KGroupId groupId() const;
559 
560  /**
561  * The name of the group.
562  * @return the name of the group
563  */
564  QString name() const;
565 
566  /**
567  * @param maxCount the maximum number of users to return
568  * @return a list of all users of the group
569  */
570  QList<KUser> users(uint maxCount = KCOREADDONS_UINT_MAX) const;
571 
572  /**
573  * @param maxCount the maximum number of groups to return
574  * @return a list of all user login names of the group
575  */
576  QStringList userNames(uint maxCount = KCOREADDONS_UINT_MAX) const;
577 
578  /**
579  * Destructor.
580  */
581  ~KUserGroup();
582 
583  /**
584  * @param maxCount the maximum number of groups to return
585  * @return a list of all groups on this system
586  */
587  static QList<KUserGroup> allGroups(uint maxCount = KCOREADDONS_UINT_MAX);
588 
589  /**
590  * @param maxCount the maximum number of groups to return
591  * @return a list of all group names on this system
592  */
593  static QStringList allGroupNames(uint maxCount = KCOREADDONS_UINT_MAX);
594 
595 private:
597 };
598 
599 #if !defined(Q_OS_WIN)
600 // inline UNIX implementation of KUserOrGroupId
601 template<typename T>
602 inline bool KUserOrGroupId<T>::isValid() const
603 {
604  return id != NativeType(-1);
605 }
606 template<typename T>
607 inline bool KUserOrGroupId<T>::operator==(const KUserOrGroupId<T> &other) const
608 {
609  return id == other.id;
610 }
611 template<typename T>
612 inline bool KUserOrGroupId<T>::operator!=(const KUserOrGroupId<T> &other) const
613 {
614  return id != other.id;
615 }
616 template<typename T>
617 inline typename KUserOrGroupId<T>::NativeType KUserOrGroupId<T>::nativeId() const
618 {
619  return id;
620 }
621 template<typename T>
623 {
624  return QString::number(id);
625 }
626 template<typename T>
628  : id(-1)
629 {
630 }
631 template<typename T>
632 inline KUserOrGroupId<T>::KUserOrGroupId(KUserOrGroupId<T>::NativeType nativeId)
633  : id(nativeId)
634 {
635 }
636 template<typename T>
638  : id(other.id)
639 {
640 }
641 template<typename T>
643 {
644  id = other.id;
645  return *this;
646 }
647 template<typename T>
649 {
650 }
651 #endif // !defined(Q_OS_WIN)
652 
653 inline bool KUser::operator!=(const KUser &other) const
654 {
655  return !operator==(other);
656 }
657 
658 inline bool KUserGroup::operator!=(const KUserGroup &other) const
659 {
660  return !operator==(other);
661 }
662 
663 #endif
KUserId()
Creates an invalid KUserId.
Definition: kuser.h:135
Use the effective user id.
Definition: kuser.h:229
NativeType nativeId() const
Definition: kuser.h:617
Represents a group on your system.
Definition: kuser.h:457
Use the real user id.
Definition: kuser.h:230
QString toString() const
Definition: kuser.h:622
bool isValid() const
Definition: kuser.h:602
bool operator==(const KUserOrGroupId &other) const
Definition: kuser.h:607
bool operator!=(const KUser &user) const
Two KUser objects are not equal if userId() are not identical.
Definition: kuser.h:653
Represents a user on your system.
Definition: kuser.h:225
KUserOrGroupId()
Creates an invalid KUserOrGroupId.
Definition: kuser.h:627
QString number(int n, int base)
KCALENDARCORE_EXPORT uint qHash(const KCalendarCore::Period &key)
UIDMode
Definition: kuser.h:228
KUserId(K_UID uid)
Creates an KUserId from the native user ID type.
Definition: kuser.h:139
A platform independent group ID.
Definition: kuser.h:168
KGroupId()
Creates an invalid KGroupId.
Definition: kuser.h:170
bool operator!=(const KUserOrGroupId &other) const
Definition: kuser.h:612
KGroupId(K_GID gid)
Creates an KGroupId from the native group ID type.
Definition: kuser.h:174
bool operator!=(const KUserGroup &group) const
Two KUserGroup objects are not equal if their gid()s are not identical.
Definition: kuser.h:658
A platform independent user ID.
Definition: kuser.h:133
A platform independent user or group ID.
Definition: kuser.h:59
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Fri Apr 9 2021 23:01:38 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.