netinfo.subproj/netinfo.3

   1 .TH NETINFO 3 "August 29, 1989" "Apple Computer, Inc."
   2 .SH NAME
   3 netinfo \- library routines for NetInfo calls
   4 .SH SYNOPSIS
   5 \fB#include <netinfo/ni.h>\fR
   6 .SH DESCRIPTION
   7 These calls are the programming interface to NetInfo.  Typically,
   8 a handle (of type "void *") is allocated through a call to
   9 .I ni_new,
  10 .I ni_open,
  11 or
  12 .I ni_connect.
  13 This handle opens a connection to the given NetInfo domain.  Read calls
  14 may go to either the master or the clone servers, while writes will
  15 always go to the master server.  If the master is unavailable,
  16 no writes can be performed.
  17 The handle is then passed to one of several NetInfo routines for database
  18 operations and then freed using
  19 .I ni_free.
  20 Several utility routines are also supplied which operate on NetInfo data
  21 structures.  These routines don't require NetInfo handles.
  22 .LP
  23 .SH MACROS
  24 .PP
  25 .B NI_INDEX_NULL
  26 .IP
  27 A constant which evaluates to the highest unsigned integer.  It is useful
  28 for indicating something which should go at the end of a list, as opposed
  29 to a smaller value which indicates the precise position at which the insert
  30 should occur.
  31 .PP
  32 \fBNI_INIT\fR(\fIptr\fR)
  33 .IP
  34 Initializes a NetInfo data structure.  It effectively zeros out the structure
  35 referred to by
  36 .I ptr.
  37 This macro is useful for indicating an empty list or NULL value with one
  38 of the many NetInfo data structures.
  39 .SH "DATATYPES AND ASSOCIATED UTILITY ROUTINES"
  40 .PP
  41 .B ni_status
  42 .IP
  43 The result code of most NetInfo routines.
  44 .PP
  45 const char *\fBni_error\fR(ni_status \fIstatus\fR)
  46 .IP
  47 Returns the error string associated with the given NetInfo status.
  48 .PP
  49 .B ni_index
  50 .IP
  51 An index into a NetInfo list.
  52 .PP
  53 .B ni_id
  54 .IP
  55 NetInfo directories are identified through the
  56 .I ni_id
  57 data structure.  It records the ID of the directory in the
  58 .I nii_object
  59 field and the instance of the directory in the
  60 .I nii_instance
  61 field.  The instance indicates which version of the directory is being
  62 operated on and is only relevant for writes.  Each time a write is
  63 performed, the instance is incremented to reflect the new version.  If
  64 the instance given does not match the current instance of the directory,
  65 the error NI_STALE is returned, indicating a stale ID.  All NetInfo
  66 routines which operate on directories will return the latest value of
  67 the instance.
  68 .PP
  69 .B ni_name
  70 .IP
  71 A NetInfo name.  It is equivalent to a C string.
  72 .PP
  73 ni_name \fBni_name_dup\fR(const ni_name \fIname\fR)
  74 .IP
  75 Returns a mallocated copy of a NetInfo name.
  76 .PP
  77 void \fBni_name_free\fR(ni_name *\fInamep\fR)
  78 .IP
  79 Frees a NetInfo name.  The pointer is converted to NULL.  A NULL pointer
  80 will not be freed.
  81 .PP
  82 int \fBni_name_match\fR(const ni_name \fIname1\fR, const ni_name \fIname2\fR)
  83 .IP
  84 Compares two NetInfo names for equality.  Returns non-zero for success,
  85 zero for failure.
  86 .PP
  87 .B ni_namelist
  88 .IP
  89 A list of NetInfo names.
  90 .PP
  91 ni_namelist \fBni_namelist_dup\fR(const ni_namelist \fInl\fR)
  92 .IP
  93 Returns a mallocated duplicate of a NetInfo namelist.
  94 .PP
  95 void \fBni_namelist_free\fR(ni_namelist *\fInl\fR)
  96 .IP
  97 Frees a NetInfo namelist.  The namelist structure is zeroed.  Zeroed
  98 namelists will not be freed.
  99 .PP
 100 void \fBni_namelist_insert\fR(ni_namelist *\fInl\fR, const ni_name \fIname\fR, ni_index \fIwhere\fR)
 101 .IP
 102 Duplicates and inserts the given name at the given location into the namelist.
 103 .PP
 104 void \fBni_namelist_delete\fR(ni_namelist *\fInl\fR, ni_index \fIwhere\fR)
 105 .IP
 106 Deletes and frees the name at the given location in the namelist.
 107 .PP
 108 ni_index \fBni_namelist_match\fR(const ni_namelist \fInl\fR, const ni_name \fIname\fR)
 109 .IP
 110 If the name is in the given namelist, the first index of its occurrence
 111 is returned.  Otherwise, NI_INDEX_NULL is returned indicating failure.
 112 .PP
 113 .B ni_property
 114 .IP
 115 A NetInfo property.  It contains a name and a namelist of associated values.
 116 .PP
 117 ni_property \fBni_prop_dup\fR(const ni_property \fIprop\fR)
 118 .IP
 119 Returns a mallocated duplicate of the given NetInfo property.
 120 .PP
 121 void \fBni_prop_free\fR(ni_property *\fIprop\fR)
 122 .IP
 123 Frees and zeros the NetInfo property.  Zeroed properties will not be freed
 124 again.
 125 .PP
 126 .B ni_proplist
 127 .IP
 128 A list of NetInfo properties.
 129 .PP
 130 void \fBni_proplist_insert\fR(ni_proplist *\fIpl\fR, const ni_property \fIprop\fR, ni_index \fIwhere\fR)
 131 .IP
 132 Duplicates and inserts the given property at the given location into the given property
 133 list.
 134 .PP
 135 void \fBni_proplist_delete\fR(ni_proplist *\fIpl\fR, ni_index \fIwhere\fR)
 136 .IP
 137 Frees and deletes the property at the given location in the property list.
 138 .PP
 139 ni_index \fBni_proplist_match\fR(const ni_proplist \fIpl\fR, const ni_name \fIname\fR, const ni_name \fIval\fR)
 140 .IP
 141 Returns the location in the property list of the first property with a name
 142 of
 143 .I name
 144 and having value
 145 .I val.
 146 NI_INDEX_NULL is returned on failure.
 147 If NULL is the \fIvalue\fR argument,
 148 \fBni_proplist_match\fR will match on only the \fIname\fR argument.
 149 .PP
 150 ni_proplist \fBni_proplist_dup\fR(const ni_proplist \fIpl\fR)
 151 .IP
 152 Returns a mallocated duplicate property list.
 153 .PP
 154 void \fBni_proplist_free\fR(ni_proplist *\fIpl\fR)
 155 .IP
 156 Frees and zeroes the property list.  A zeroed property will not be freed again.
 157 .PP
 158 .B ni_idlist
 159 .IP
 160 A list of NetInfo indices (usually directory ID's).
 161 .PP
 162 void \fBni_idlist_free\fR(ni_idlist *\fIidl\fR)
 163 .IP
 164 Frees and zeroes the given ID list.  A zeroed ID list will not be freed again.
 165 .PP
 166 .B ni_entry
 167 .IP
 168 An entry in a NetInfo directory.  It contains the ID of the directory and
 169 a list of values assocated with whatever property was requested in the
 170 .I ni_list
 171 routine.  The list may be NULL, indicating that there is not associated
 172 property for this directory.
 173 .PP
 174 .B ni_entrylist
 175 .IP
 176 A list of NetInfo entries.
 177 .PP
 178 void \fBni_entrylist_free\fR(ni_entrylist *\fIentries\fR)
 179 .IP
 180 Frees and zeros the given entry list.  A zeroed entry list will not be
 181 freed again.
 182 .LP
 183 .SH "ROUTINES"
 184 .PP
 185 ni_status \fBni_addrtag\fR(void *\fIhandle\fR, struct sockaddr_in *\fIaddr\fR, ni_name *\fItag\fR)
 186 .IP
 187 Returns the address and domain tag associated with the connected
 188 NetInfo handle.
 189 .PP
 190 ni_status \fBni_children\fR(void *\fIhandle\fR, ni_id *\fIdir\fR, ni_idlist *\fIidlist\fR)
 191 .IP
 192 Lists the children ID's (subdirectories) of the given directory.
 193 .PP
 194 void *\fBni_connect\fR(struct sockaddr_in *\fIaddr\fR, ni_name \fItag\fR)
 195 .IP
 196 Returns a NetInfo handle to the NetInfo domain at the given address
 197 and domain tag.  Returns NULL on failure.
 198 .PP
 199 ni_status \fBni_create\fR(void *\fIhandle\fR, ni_id *\fIparent\fR, ni_proplist \fIprops\fR, ni_id *\fIchild\fR, ni_index \fIwhere\fR)
 200 .IP
 201 Creates a new directory at the given index initialized with the given
 202 properties.
 203 .PP
 204 ni_status \fBni_createname\fR(void *\fIhandle\fR, ni_id *\fIdir\fR, ni_index \fIprop_index\fR, ni_name \fIname\fR, ni_index \fIval_index\fR)
 205 .IP
 206 Inserts the name into the value list of the given directory at the property
 207 indexed by prop_index and value list location val_index.
 208 .PP
 209 ni_status \fBni_createprop\fR(void *\fIhandle\fR, ni_id *\fIdir\fR, ni_property \fIprop\fR, ni_index \fIwhere\fR)
 210 .IP
 211 Creates a new property at the given index in the given directory.
 212 .PP
 213 ni_status \fBni_destroy\fR(void *\fIhandle\fR, ni_id *\fIparent\fR, ni_id \fIchild\fR)
 214 .IP
 215 Destroys the directory child in the given parent directory.  Both instance
 216 must be the latest values or the error NI_STALE is returned.
 217 .PP
 218 ni_status \fBni_destroyname\fR(void *\fIhandle\fR, ni_id *\fIdir\fR, ni_index \fIprop_index\fR, ni_index \fIval_index\fR)
 219 .IP
 220 Destroys a property value in the given directory at the given prop_index and
 221 value-list val_index.
 222 .PP
 223 ni_status \fBni_destroyprop\fR(void *\fIhandle\fR, ni_id *\fIdir\fR, ni_index \fIwhere\fR)
 224 .IP
 225 Destroys the property at property index
 226 .I where
 227 in the given directory.
 228 .PP
 229 ni_status \fBni_fancyopen\fR(void *\fIhandle\fR, ni_name \fIdomain\fR, void **\fIrethandle\fR, ni_fancyopenargs *\fIargs\fR)
 230 .PP
 231 .nf
 232 typedef struct ni_fancyopenargs {
 233         int rtimeout;
 234         int wtimeout;
 235         int abort;
 236         int needwrite;
 237 } ni_fancyopenargs;
 238 .fi
 239 .IP
 240 A fancier version of ni_open which allows one to set
 241 various attributes on the the returned handle. See
 242 .I ni_setreadtimeout(),
 243 .I ni_setwritetimeout(),
 244 .I ni_setabort()
 245 and
 246 .I ni_needwrite()
 247 for descriptions of the fields
 248 in the ni_fancyopenargs structure. A 0 in the
 249 rtimeout or wtimeout field indicates the
 250 default timeout should be used.
 251 .PP
 252 void \fBni_free\fR(void *\fIhandle\fR)
 253 .IP
 254 Frees a NetInfo handle and closes any associated connections.
 255 .PP
 256 ni_status \fBni_list\fR(void *\fIhandle\fR, ni_id *\fIdir\fR , ni_name \fIname\fR, ni_entrylist *\fIentries\fR)
 257 .IP
 258 Lists all the subdirectories of the given directory along with any associated
 259 values they may have for the property
 260 .I name.
 261 If a subdirectory doesn't have the property \fIname\fR,
 262 the entry is still returned but with a NULL property list.
 263 .PP
 264 ni_status \fBni_listprops\fR(void *\fIhandle\fR, ni_id *\fIdir\fR, ni_namelist *\fInl\fR)
 265 .IP
 266 Returns the list of property names associated with the given directory.
 267 .PP
 268 ni_status \fBni_lookup\fR(void *\fIhandle\fR, ni_id *\fIdir\fR, ni_name \fIname\fR, ni_name \fIval\fR, ni_idlist *\fIfound\fR)
 269 .IP
 270 Returns a list of subdirectories which satisfy the relation
 271 .I name
 272 equals
 273 .I val.
 274 .PP
 275 ni_status \fBni_lookupprop\fR(void *\fIhandle\fR, ni_id *\fIdir\fR, ni_name \fIname\fR, ni_namelist *\fIval\fR)
 276 .IP
 277 Returns the values associated with the property named
 278 .I name
 279 in the given directory.
 280 .PP
 281 ni_status \fBni_lookupread\fR(void *\fIhandle\fR, ni_id *\fIdirid\fR, ni_name \fIpropname\fR, ni_name \fIpropval\fR, ni_proplist *\fIprops\fR)
 282 .IP
 283 Looks up the subdirectory given the
 284 .I (propname, propval\)
 285 pair
 286 and returns the subdirectory's properties. This call is equivalent to
 287 an
 288 .I ni_lookup()
 289 followed by an
 290 .I ni_read().
 291 .PP
 292 void \fBni_needwrite\fR(void *\fIhandle\fR, int \fIneedwrite\fR)
 293 .IP
 294 Indicates whether subsequent calls will need to write to a
 295 netinfo server. By default, the flag is off and the netinfo
 296 library will automatically switch to a server capable of
 297 writing whenever a write call occurs. However, since writes
 298 may take some time to reach the clone server, one could read
 299 stale information from a clone server and then attempt to
 300 write the master based upon the stale information. Setting
 301 .I needwrite
 302 will lock the handle onto the master netinfo server even for
 303 reads to prevent this from happening.
 304 .PP
 305 ni_status \fBni_open\fR(void *\fIrelativeto\fR, ni_name \fIdomain\fR, void **\fIresult\fR)
 306 .IP
 307 Opens a connection to the NetInfo domain
 308 .I domain.
 309 The returned handle is opened relative to the domain specified in the
 310 .I relativeto.
 311 This handle may be passed as NULL, indicating relative to the local
 312 NetInfo domain.  The path may contain "/"s to indicate a multilevel
 313 search and may also be "." or ".." to indicate the current domain or
 314 parent domain, respectively.
 315 .PP
 316 ni_status \fBni_parent\fR(void *\fIhandle\fR, ni_id *\fIdir\fR, ni_index *\fIparent_id\fR)
 317 .IP
 318 Returns the parent ID of the given directory.
 319 .PP
 320 ni_status \fBni_pathsearch\fR(void *\fIhandle\fR, ni_id *\fIdir\fR, ni_name \fIpath\fR)
 321 .IP
 322 Does a multilevel lookup on a directory, relative to the given directory
 323 ID.  The path may contain "/"s to separative directory components.  "="s
 324 are used to specify relations and both may be escaped using "\\"s.  For
 325 example, to find the directory associated with the superuser, you may
 326 specify (relative to the root directory) "/name=users/uid=0".  Note that
 327 the equal signs are not mandatory and will default to "name=" if none
 328 are specified.  In the previous example, "/users/uid=0" would accomplish
 329 the same result.
 330 .PP
 331 ni_status \fBni_read\fR(void *\fIhandle\fR, ni_id *\fIdir\fR, ni_proplist *\fIprops\fR)
 332 .IP
 333 Reads all of the properties of the given directory.
 334 .PP
 335 ni_status \fBni_readname\fR(void *\fIhandle\fR, ni_id *\fIdir\fR, ni_index \fIprop_index\fR, ni_index \fIval_index\fR, ni_name *\fIvalue\fR)
 336 .IP
 337 Reads a value from a property in the given directory.  The value is indexed
 338 by property index
 339 .I prop_index
 340 and value index
 341 .I val_index.
 342 .PP
 343 ni_status \fBni_readprop\fR(void *\fIhandle\fR, ni_id *\fIdir\fR, ni_index \fIprop_index\fr, ni_namelist *\fInl\fR)
 344 .IP
 345 Reads the value-list associated with the given property, indexed by
 346 .I prop_index.
 347 .PP
 348 ni_status \fBni_renameprop\fR(void *\fIhandle\fR, ni_id *\fIdir\fR, ni_index \fIprop_index\fR, ni_name \fInewname\fR)
 349 .IP
 350 Renames the property indexed by
 351 .I prop_index
 352 to the new name
 353 .I newname.
 354 .PP
 355 ni_status \fBni_resync\fR(void *\fIhandle\fR)
 356 .IP
 357 Attempts to resynchronize the clone servers with the master copy of
 358 the database.
 359 .PP
 360 ni_status \fBni_root\fR(void *\fIhandle\fR, ni_id *\fIdir\fR)
 361 .IP
 362 Returns the directory ID of the root of the directory tree.
 363 .PP
 364 ni_status \fBni_self\fR(void *\fIhandle\fR, ni_id *\fIdir\fR)
 365 .IP
 366 Returns the directory ID of the given directory.  Simply refreshes the
 367 instance field to the latest value.
 368 .PP
 369 void \fBni_setabort\fR(void *\fIhandle\fR, int \fIshouldabort\fR)
 370 .IP
 371 By default, netinfo calls will try forever until an answer
 372 is returned from a server.
 373 .I ni_setabort
 374  allows one to have
 375 netinfo return failure upon the first timeout or other failure.
 376 .PP
 377 ni_status \fBni_setpassword\fR(void *\fIhandle\fR, ni_name \fIpassword\fR)
 378 .IP
 379 Sets the password for the session to
 380 .I password.
 381 By default, no password is sent.
 382 .PP
 383 void \fBni_setreadtimeout\fR(void *\fIhandle\fR, int \fIseconds\fR)
 384 .IP
 385 Sets the timeout associated with reads on netinfo. The timeout
 386 is only a hint and the effective timeout may be longer. Note
 387 that calls will not abort even if a timeout is set unless the
 388 abort flag has been set (see
 389 .I ni_setabort()).
 390 .PP
 391 ni_status \fBni_setuser\fr(void *\fIhandle\fR, ni_name \fIusername\fR)
 392 .IP
 393 Changes the username associated with the session.  By default, the username
 394 is the one associated with the user-ID that was used during the UNIX login
 395 process.
 396 .PP
 397 void \fBni_setwritetimeout\fR(void *\fIhandle\fR, int \fIseconds\fR)
 398 .IP
 399 Sets the timeout associated with writes on netinfo. The timeout
 400 is only a hint and the effective timeout may be a longer. Note
 401 that calls will not abort even if a timeout is set unless the
 402 abort flag has been set (see
 403 .I ni_setabort()).
 404 .PP
 405 ni_status \fBni_statistics\fR(void *\fIhandle\fR, ni_proplist *\fIstatistics\fR)
 406 .IP
 407 Returns various statistics from the server.
 408 .PP
 409 ni_status \fBni_write\fR(void *\fIhandle\fR, ni_id *\fIdir\fR, ni_proplist \fIprops\fR)
 410 .IP
 411 Writes a new property list to the directory.
 412 .PP
 413 ni_status \fBni_writename\fr(void *\fIhandle\fR, ni_id *\fIdir\fR, ni_index \fIprop_index\fr, ni_index \fIname_index\fR, ni_name \fIval\fR)
 414 .IP
 415 Writes a new property value to the property indexed by
 416 .I prop_index
 417 and value indexed by
 418 .I val_index.
 419 .PP
 420 ni_status \fBni_writeprop\fr(void *\fIhandle\fR, ni_id *\fIdir\fR, ni_index \fIprop_index\fR, ni_namelist \fIvalues\fR)
 421 .IP
 422 Writes a new value list to the property indexed by
 423 .I prop_index.
 424 It is allowable to have more than one property with the same name.
 425 .IP