os/ossrv/genericopenlibs/openenvcore/include/pwd.dosc
author sl
Tue, 10 Jun 2014 14:32:02 +0200
changeset 1 260cb5ec6c19
permissions -rw-r--r--
Update contrib.
sl@0
     1
/** @file  ../include/pwd.h
sl@0
     2
@internalComponent
sl@0
     3
*/
sl@0
     4
sl@0
     5
sl@0
     6
/** @fn  getpwnam(const char *name)
sl@0
     7
@param name
sl@0
     8
sl@0
     9
Refer to  getpwent() for the documentation
sl@0
    10
sl@0
    11
@see getgrent()
sl@0
    12
sl@0
    13
sl@0
    14
 
sl@0
    15
sl@0
    16
@publishedAll
sl@0
    17
@externallyDefinedApi
sl@0
    18
*/
sl@0
    19
sl@0
    20
/** @fn  getpwuid(uid_t uid)
sl@0
    21
@param uid
sl@0
    22
sl@0
    23
Refer to  getpwent() for the documentation
sl@0
    24
sl@0
    25
@see getgrent()
sl@0
    26
sl@0
    27
sl@0
    28
 
sl@0
    29
sl@0
    30
@publishedAll
sl@0
    31
@externallyDefinedApi
sl@0
    32
*/
sl@0
    33
sl@0
    34
/** @fn  endpwent(void)
sl@0
    35
sl@0
    36
Refer to  getpwent() for the documentation
sl@0
    37
@see getgrent()
sl@0
    38
sl@0
    39
sl@0
    40
 
sl@0
    41
sl@0
    42
@publishedAll
sl@0
    43
@externallyDefinedApi
sl@0
    44
*/
sl@0
    45
sl@0
    46
/** @fn  getpwent(void)
sl@0
    47
sl@0
    48
Note: This description also covers the following functions -
sl@0
    49
 getpwnam()  getpwnam_r()  getpwuid()  getpwuid_r()  setpwent()  endpwent() 
sl@0
    50
sl@0
    51
@return   The functions getpwent, getpwnam, and getpwuid return a valid pointer to a passwd structure on success
sl@0
    52
or NULL if the entry is not found or if an error occurs.
sl@0
    53
If an error does occur, errno will be set.
sl@0
    54
The functions getpwnam_r, and getpwuid_r return 0 if no error occurred, or an error number to indicate failure.
sl@0
    55
It is not an error if a matching entry is not found.
sl@0
    56
(Thus, if result is NULL and the return value is 0, no matching entry exists.) The endpwent and setpwent functions
sl@0
    57
have no return value.
sl@0
    58
sl@0
    59
These APIs belongs to set which are only build supported and not available functionally. The reason why only build support is extended to these APIs is that Symbian operating system does not support the creation of multiple users and groups in its environment. Moreover it may not make sense to have multiple users and groups in the context of a mobile environment. 
sl@0
    60
We refer to the structure  
sl@0
    61
@code
sl@0
    62
#include <pwd.h> 
sl@0
    63
struct passwd {
sl@0
    64
        char    *pw_name;       /* user name */
sl@0
    65
        char    *pw_passwd;     /* encrypted password */
sl@0
    66
        uid_t   pw_uid;         /* user uid */
sl@0
    67
        gid_t   pw_gid;         /* user gid */
sl@0
    68
        time_t  pw_change;      /* password change time */
sl@0
    69
        char    *pw_class;      /* user access class */
sl@0
    70
        char    *pw_gecos;      /* Honeywell login info */
sl@0
    71
        char    *pw_dir;        /* home directory */
sl@0
    72
        char    *pw_shell;      /* default shell */
sl@0
    73
        time_t  pw_expire;      /* account expiration */
sl@0
    74
        int     pw_fields;      /* internal: fields filled in */
sl@0
    75
};
sl@0
    76
sl@0
    77
@endcode
sl@0
    78
sl@0
    79
sl@0
    80
The functions getpwnam and getpwuid returns the default values for a single user system i.e., pw_name,pw_passwd,pw_uid and pw_gid set to root,NULL,0 and 0 respectively in case the input parameter uid/login is 0/ root else the error number is set and NULL is returned by the APIs. 
sl@0
    81
sl@0
    82
The getpwent when called the first time by an application returns the pointer to a valid passwd structure,that of the simulated single-user group.Subsequent calls return NULL until setpwent is called 
sl@0
    83
sl@0
    84
The functions getpwnam_r, and getpwuid_r are thread-safe versions of getpwnam, and getpwuid, respectively. The caller must provide storage for the results of the search in the pwd, buffer, bufsize, and result arguments. When these functions are successful, the pwd argument will be filled-in, and a pointer to that argument will be stored in result. If an entry is not found or an error occurs, result will be set to NULL. 
sl@0
    85
sl@0
    86
The setpwent function sets the library such that subsequent getpwent call returns a filled passwd structure. 
sl@0
    87
sl@0
    88
endpwent function sets up the library such that the subsequent getpwent call returns NULL. 
sl@0
    89
 
sl@0
    90
sl@0
    91
sl@0
    92
sl@0
    93
sl@0
    94
sl@0
    95
@see getgrent()
sl@0
    96
sl@0
    97
sl@0
    98
Bugs:
sl@0
    99
sl@0
   100
 The functions getpwent, getpwnam, and getpwuid, leave their results in an internal static object and return
sl@0
   101
a pointer to that object.
sl@0
   102
Subsequent calls to
sl@0
   103
the same function
sl@0
   104
will modify the same object. The functions getpwent, endpwent, and setpwent are fairly useless in a networked environment and should be
sl@0
   105
avoided, if possible. 
sl@0
   106
sl@0
   107
 
sl@0
   108
sl@0
   109
@publishedAll
sl@0
   110
@externallyDefinedApi
sl@0
   111
*/
sl@0
   112
sl@0
   113
/** @fn  setpwent(void)
sl@0
   114
sl@0
   115
Refer to  getpwent() for the documentation
sl@0
   116
@see getgrent()
sl@0
   117
sl@0
   118
sl@0
   119
 
sl@0
   120
sl@0
   121
@publishedAll
sl@0
   122
@externallyDefinedApi
sl@0
   123
*/
sl@0
   124
sl@0
   125
/** @fn  getpwnam_r(const char *name, struct passwd *pwd, char *, size_t, struct passwd **result)
sl@0
   126
@param name
sl@0
   127
@param pwd
sl@0
   128
@param result
sl@0
   129
sl@0
   130
Refer to  getpwent() for the documentation
sl@0
   131
sl@0
   132
@see getgrent()
sl@0
   133
sl@0
   134
sl@0
   135
 
sl@0
   136
sl@0
   137
@publishedAll
sl@0
   138
@externallyDefinedApi
sl@0
   139
*/
sl@0
   140
sl@0
   141
/** @fn  getpwuid_r(uid_t uid, struct passwd *pwd, char *, size_t, struct passwd **result)
sl@0
   142
@param uid
sl@0
   143
@param pwd
sl@0
   144
@param result
sl@0
   145
sl@0
   146
Refer to  getpwent() for the documentation
sl@0
   147
sl@0
   148
@see getgrent()
sl@0
   149
sl@0
   150
sl@0
   151
 
sl@0
   152
sl@0
   153
@publishedAll
sl@0
   154
@externallyDefinedApi
sl@0
   155
*/
sl@0
   156
sl@0
   157
/** @struct passwd
sl@0
   158
sl@0
   159
The passwd data structure is used to hold information about entries in the system user data base
sl@0
   160
sl@0
   161
@publishedAll
sl@0
   162
@externallyDefinedApi
sl@0
   163
*/
sl@0
   164
sl@0
   165
/** @var passwd::pw_name
sl@0
   166
user name
sl@0
   167
*/
sl@0
   168
sl@0
   169
/** @var passwd::pw_passwd
sl@0
   170
encrypted password
sl@0
   171
*/
sl@0
   172
sl@0
   173
/** @var passwd::pw_uid
sl@0
   174
user uid
sl@0
   175
*/
sl@0
   176
sl@0
   177
/** @var passwd::pw_gid
sl@0
   178
user gid
sl@0
   179
*/
sl@0
   180
sl@0
   181
/** @var passwd::pw_change
sl@0
   182
password change time 
sl@0
   183
*/
sl@0
   184
sl@0
   185
/** @var passwd::pw_class
sl@0
   186
user access class
sl@0
   187
*/
sl@0
   188
sl@0
   189
/** @var passwd::pw_gecos
sl@0
   190
 login info
sl@0
   191
*/
sl@0
   192
sl@0
   193
/** @var passwd::pw_dir
sl@0
   194
home directory
sl@0
   195
*/
sl@0
   196
sl@0
   197
/** @var passwd::pw_shell
sl@0
   198
default shell
sl@0
   199
*/
sl@0
   200
sl@0
   201
/** @var passwd::pw_expire
sl@0
   202
account expiration
sl@0
   203
*/
sl@0
   204
sl@0
   205
/** @var passwd::pw_fields
sl@0
   206
internal: fields filled in
sl@0
   207
*/
sl@0
   208
sl@0
   209
/** @def _PATH_PWD
sl@0
   210
sl@0
   211
Defines to "//etc"
sl@0
   212
sl@0
   213
@publishedAll
sl@0
   214
@released
sl@0
   215
*/
sl@0
   216
sl@0
   217
sl@0
   218
/** @def _PATH_PASSWD	
sl@0
   219
sl@0
   220
Defines to "//etc//passwd"
sl@0
   221
	
sl@0
   222
@publishedAll
sl@0
   223
@released
sl@0
   224
*/
sl@0
   225
sl@0
   226
sl@0
   227
/** @def _PASSWD	
sl@0
   228
sl@0
   229
Defines to "passwd"
sl@0
   230
		
sl@0
   231
@publishedAll
sl@0
   232
@released
sl@0
   233
*/
sl@0
   234
sl@0
   235
sl@0
   236
/** @def _PATH_MASTERPASSWD	
sl@0
   237
sl@0
   238
Defines to "//etc//master.passwd"
sl@0
   239
sl@0
   240
@publishedAll
sl@0
   241
@released
sl@0
   242
*/
sl@0
   243
sl@0
   244
/** @def _MASTERPASSWD		
sl@0
   245
sl@0
   246
"master.passwd"
sl@0
   247
sl@0
   248
@publishedAll
sl@0
   249
@released
sl@0
   250
*/
sl@0
   251
sl@0
   252
sl@0
   253
/** @def _PATH_MP_DB	
sl@0
   254
sl@0
   255
Defines to "//etc//pwd.db"
sl@0
   256
	
sl@0
   257
@publishedAll
sl@0
   258
@released
sl@0
   259
*/
sl@0
   260
sl@0
   261
sl@0
   262
/** @def _MP_DB		
sl@0
   263
sl@0
   264
Defines to "pwd.db"
sl@0
   265
	
sl@0
   266
@publishedAll
sl@0
   267
@released
sl@0
   268
*/
sl@0
   269
sl@0
   270
sl@0
   271
sl@0
   272
/** @def _PATH_SMP_DB		
sl@0
   273
sl@0
   274
Defines to "//etc//spwd.db"
sl@0
   275
sl@0
   276
@publishedAll
sl@0
   277
@released
sl@0
   278
*/
sl@0
   279
sl@0
   280
sl@0
   281
/** @def _SMP_DB	
sl@0
   282
sl@0
   283
Defines to "spwd.db"
sl@0
   284
		
sl@0
   285
@publishedAll
sl@0
   286
@released
sl@0
   287
*/
sl@0
   288
sl@0
   289
sl@0
   290
/** @def _PATH_PWD_MKDB		
sl@0
   291
sl@0
   292
Defines to "//usr//sbin//pwd_mkdb"
sl@0
   293
sl@0
   294
@publishedAll
sl@0
   295
@released
sl@0
   296
*/
sl@0
   297
sl@0
   298
sl@0
   299
/** @def _PASSWORD_LEN	
sl@0
   300
sl@0
   301
max length, not counting NULL
sl@0
   302
	
sl@0
   303
@publishedAll
sl@0
   304
@released
sl@0
   305
*/
sl@0
   306
sl@0
   307
sl@0
   308
sl@0
   309