ni_readname man page on OPENSTEP

Man page or keyword search:  
man Server   1419 pages
apropos Keyword Search (all sections)
Output format
OPENSTEP logo
[printable version]


NETINFO(3N)							   NETINFO(3N)

NAME
       netinfo - library routines for NetInfo calls

SYNOPSIS
       #include <netinfo/ni.h>

DESCRIPTION
       These  calls  are  the  programming interface to NetInfo.  Typically, a
       handle (of type "void *")  is  allocated	 through  a  call  to  ni_new,
       ni_open,	 or  ni_connect.   This handle opens a connection to the given
       NetInfo domain.	Read calls may go to either the master	or  the	 clone
       servers,	 while	writes	will  always  go to the master server.	If the
       master is unavailable, no writes can be performed.  The handle is  then
       passed  to  one of several NetInfo routines for database operations and
       then freed using ni_free.  Several utility routines are	also  supplied
       which operate on NetInfo data structures.  These routines don't require
       NetInfo handles.

MACROS
       NI_INDEX_NULL

	      A constant which evaluates to the highest unsigned integer.   It
	      is useful for indicating something which should go at the end of
	      a list, as opposed  to  a	 smaller  value	 which	indicates  the
	      precise position at which the insert should occur.

       NI_INIT(ptr)

	      Initializes  a NetInfo data structure.  It effectively zeros out
	      the structure referred to by ptr.	  This	macro  is  useful  for
	      indicating  an  empty  list  or  NULL value with one of the many
	      NetInfo data structures.

DATATYPES AND ASSOCIATED UTILITY ROUTINES
       ni_status

	      The result code of most NetInfo routines.

       const char *ni_error(ni_status status)

	      Returns the error	 string	 associated  with  the	given  NetInfo
	      status.

       ni_index

	      An index into a NetInfo list.

       ni_id

	      NetInfo  directories  are	 identified  through  the  ni_id  data
	      structure.  It records the ID of the directory in the nii_object
	      field  and  the  instance	 of  the directory in the nii_instance
	      field.  The instance indicates which version of the directory is
	      being  operated on and is only relevant for writes.  Each time a
	      write is performed, the instance is incremented to  reflect  the
	      new  version.   If the instance given does not match the current
	      instance of the  directory,  the	error  NI_STALE	 is  returned,
	      indicating  a  stale  ID.	 All NetInfo routines which operate on
	      directories will return the latest value of the instance.

       ni_name

	      A NetInfo name.  It is equivalent to a C string.

       ni_name ni_name_dup(const ni_name name)

	      Returns a mallocated copy of a NetInfo name.

       void ni_name_free(ni_name *namep)

	      Frees a NetInfo name.  The pointer is converted to NULL.	A NULL
	      pointer will not be freed.

       int ni_name_match(const ni_name name1, const ni_name name2)

	      Compares	two  NetInfo names for equality.  Returns non-zero for
	      success, zero for failure.

       ni_namelist

	      A list of NetInfo names.

       ni_namelist ni_namelist_dup(const ni_namelist nl)

	      Returns a mallocated duplicate of a NetInfo namelist.

       void ni_namelist_free(ni_namelist *nl)

	      Frees a NetInfo namelist.	 The  namelist	structure  is  zeroed.
	      Zeroed namelists will not be freed.

       void  ni_namelist_insert(ni_namelist  *nl, const ni_name name, ni_index
       where)

	      Duplicates and inserts the given name at the given location into
	      the namelist.

       void ni_namelist_delete(ni_namelist *nl, ni_index where)

	      Deletes  and  frees  the	name  at  the  given  location	in the
	      namelist.

       ni_index ni_namelist_match(const ni_namelist nl, const ni_name name)

	      If the name is in the given namelist, the	 first	index  of  its
	      occurrence  is  returned.	  Otherwise, NI_INDEX_NULL is returned
	      indicating failure.

       ni_property

	      A NetInfo property.  It  contains	 a  name  and  a  namelist  of
	      associated values.

       ni_property ni_prop_dup(const ni_property prop)

	      Returns a mallocated duplicate of the given NetInfo property.

       void ni_prop_free(ni_property *prop)

	      Frees  and  zeros	 the NetInfo property.	Zeroed properties will
	      not be freed again.

       ni_proplist

	      A list of NetInfo properties.

       void  ni_proplist_insert(ni_proplist  *pl,  const   ni_property	 prop,
       ni_index where)

	      Duplicates  and inserts the given property at the given location
	      into the given property list.

       void ni_proplist_delete(ni_proplist *pl, ni_index where)

	      Frees and deletes the property at	 the  given  location  in  the
	      property list.

       ni_index	 ni_proplist_match(const  ni_proplist  pl, const ni_name name,
       const ni_name val)

	      Returns the location in the property list of the first  property
	      with  a  name  of	 name  and having value val.  NI_INDEX_NULL is
	      returned	on  failure.   If  NULL	  is   the   value   argument,
	      ni_proplist_match will match on only the name argument.

       ni_proplist ni_proplist_dup(const ni_proplist pl)

	      Returns a mallocated duplicate property list.

       void ni_proplist_free(ni_proplist *pl)

	      Frees  and zeroes the property list.  A zeroed property will not
	      be freed again.

       ni_idlist

	      A list of NetInfo indices (usually directory ID's).

       void ni_idlist_free(ni_idlist *idl)

	      Frees and zeroes the given ID list.  A zeroed ID list  will  not
	      be freed again.

       ni_entry

	      An  entry	 in  a	NetInfo	 directory.  It contains the ID of the
	      directory and a list of values assocated with whatever  property
	      was  requested  in  the  ni_list routine.	 The list may be NULL,
	      indicating that  there  is  not  associated  property  for  this
	      directory.

       ni_entrylist

	      A list of NetInfo entries.

       void ni_entrylist_free(ni_entrylist *entries)

	      Frees  and zeros the given entry list.  A zeroed entry list will
	      not be freed again.

ROUTINES
       ni_status ni_addrtag(void *handle, struct  sockaddr_in  *addr,  ni_name
       *tag)

	      Returns the address and domain tag associated with the connected
	      NetInfo handle.

       ni_status ni_children(void *handle, ni_id *dir, ni_idlist *idlist)

	      Lists the children ID's (subdirectories) of the given directory.

       void *ni_connect(struct sockaddr_in *addr, ni_name tag)

	      Returns a NetInfo handle to the  NetInfo	domain	at  the	 given
	      address and domain tag.  Returns NULL on failure.

       ni_status  ni_create(void  *handle,  ni_id  *parent, ni_proplist props,
       ni_id *child, ni_index where)

	      Creates a new directory at the given index initialized with  the
	      given properties.

       ni_status  ni_createname(void *handle, ni_id *dir, ni_index prop_index,
       ni_name name, ni_index val_index)

	      Inserts the name into the value list of the given	 directory  at
	      the  property  indexed  by  prop_index  and  value list location
	      val_index.

       ni_status ni_createprop(void *handle,  ni_id  *dir,  ni_property	 prop,
       ni_index where)

	      Creates  a  new  property	 at  the  given	 index	in  the	 given
	      directory.

       ni_status ni_destroy(void *handle, ni_id *parent, ni_id child)

	      Destroys the directory child  in	the  given  parent  directory.
	      Both instance must be the latest values or the error NI_STALE is
	      returned.

       ni_status ni_destroyname(void *handle, ni_id *dir, ni_index prop_index,
       ni_index val_index)

	      Destroys	a  property  value in the given directory at the given
	      prop_index and value-list val_index.

       ni_status ni_destroyprop(void *handle, ni_id *dir, ni_index where)

	      Destroys the property at	property  index	 where	in  the	 given
	      directory.

       ni_status  ni_fancyopen(void *handle, ni_name domain, void **rethandle,
       ni_fancyopenargs *args)

       typedef struct ni_fancyopenargs {
	    int rtimeout;
	    int wtimeout;
	    int abort;
	    int needwrite;
       } ni_fancyopenargs;

	      A fancier version of ni_open which allows	 one  to  set  various
	      attributes  on the the returned handle. See ni_setreadtimeout(),
	      ni_setwritetimeout(),  ni_setabort()  and	  ni_needwrite()   for
	      descriptions  of the fields in the ni_fancyopenargs structure. A
	      0 in the	rtimeout  or  wtimeout	field  indicates  the  default
	      timeout should be used.

       void ni_free(void *handle)

	      Frees a NetInfo handle and closes any associated connections.

       ni_status ni_list(void *handle, ni_id *dir , ni_name name, ni_entrylist
       *entries)

	      Lists all the subdirectories of the given directory  along  with
	      any associated values they may have for the property name.  If a
	      subdirectory doesn't have the property name, the entry is	 still
	      returned but with a NULL property list.

       ni_status ni_listprops(void *handle, ni_id *dir, ni_namelist *nl)

	      Returns  the  list  of  property names associated with the given
	      directory.

       ni_status ni_lookup(void *handle, ni_id	*dir,  ni_name	name,  ni_name
       val, ni_idlist *found)

	      Returns a list of subdirectories which satisfy the relation name
	      equals val.

       ni_status  ni_lookupprop(void  *handle,	ni_id  *dir,   ni_name	 name,
       ni_namelist *val)

	      Returns  the  values  associated with the property named name in
	      the given directory.

       ni_status ni_lookupread(void *handle, ni_id *dirid,  ni_name  propname,
       ni_name propval, ni_proplist *props)

	      Looks  up the subdirectory given the (propname, propval pair and
	      returns the subdirectory's properties. This call	is  equivalent
	      to an ni_lookup() followed by an ni_read().

       void ni_needwrite(void *handle, int needwrite)

	      Indicates	 whether  subsequent  calls  will  need	 to write to a
	      netinfo server. By default, the flag  is	off  and  the  netinfo
	      library will automatically switch to a server capable of writing
	      whenever a write call occurs. However,  since  writes  may  take
	      some  time  to  reach  the  clone	 server,  one could read stale
	      information from a clone server and then attempt	to  write  the
	      master  based upon the stale information. Setting needwrite will
	      lock the handle onto the master netinfo server even for reads to
	      prevent this from happening.

       ni_status ni_open(void *relativeto, ni_name domain, void **result)

	      Opens  a	connection to the NetInfo domain domain.  The returned
	      handle is	 opened	 relative  to  the  domain  specified  in  the
	      relativeto.   This  handle  may  be  passed  as NULL, indicating
	      relative to the local NetInfo domain.  The path may contain "/"s
	      to  indicate  a multilevel search and may also be "." or ".." to
	      indicate the current domain or parent domain, respectively.

       ni_status ni_parent(void *handle, ni_id *dir, ni_index *parent_id)

	      Returns the parent ID of the given directory.

       ni_status ni_pathsearch(void *handle, ni_id *dir, ni_name path)

	      Does a multilevel lookup on a directory, relative to  the	 given
	      directory ID.  The path may contain "/"s to separative directory
	      components.  "="s are used to specify relations and both may  be
	      escaped	using  "\"s.   For  example,  to  find	the  directory
	      associated with the superuser, you may specify (relative to  the
	      root  directory) "/name=users/uid=0".  Note that the equal signs
	      are not mandatory and  will  default  to	"name="	 if  none  are
	      specified.    In	the  previous  example,	 "/users/uid=0"	 would
	      accomplish the same result.

       ni_status ni_read(void *handle, ni_id *dir, ni_proplist *props)

	      Reads all of the properties of the given directory.

       ni_status ni_readname(void *handle, ni_id  *dir,	 ni_index  prop_index,
       ni_index val_index, ni_name *value)

	      Reads a value from a property in the given directory.  The value
	      is  indexed  by  property	 index	prop_index  and	 value	 index
	      val_index.

       ni_status  ni_readprop(void  *handle,  ni_id *dir, ni_index prop_index,
       ni_namelist *nl)

	      Reads the value-list associated with the given property, indexed
	      by prop_index.

       ni_status  ni_renameprop(void *handle, ni_id *dir, ni_index prop_index,
       ni_name newname)

	      Renames the property indexed  by	prop_index  to	the  new  name
	      newname.

       ni_status ni_resync(void *handle)

	      Attempts to resynchronize the clone servers with the master copy
	      of the database.

       ni_status ni_root(void *handle, ni_id *dir)

	      Returns the directory ID of the root of the directory tree.

       ni_status ni_self(void *handle, ni_id *dir)

	      Returns  the  directory  ID  of  the  given  directory.	Simply
	      refreshes the instance field to the latest value.

       void ni_setabort(void *handle, int shouldabort)

	      By  default,  netinfo  calls will try forever until an answer is
	      returned from a server.  ni_setabort
	       allows one to  have  netinfo  return  failure  upon  the	 first
	      timeout or other failure.

       ni_status ni_setpassword(void *handle, ni_name password)

	      Sets  the	 password  for the session to password. By default, no
	      password is sent.

       void ni_setreadtimeout(void *handle, int seconds)

	      Sets the timeout associated with reads on netinfo.  The  timeout
	      is  only	a  hint	 and the effective timeout may be longer. Note
	      that calls will not abort even if a timeout is  set  unless  the
	      abort flag has been set (see ni_setabort()).

       ni_status ni_setuser(void *handle, ni_name username)

	      Changes  the  username associated with the session.  By default,
	      the username is the one associated with  the  user-ID  that  was
	      used during the UNIX login process.

       void ni_setwritetimeout(void *handle, int seconds)

	      Sets  the timeout associated with writes on netinfo. The timeout
	      is only a hint and the effective timeout may be a	 longer.  Note
	      that  calls  will	 not abort even if a timeout is set unless the
	      abort flag has been set (see ni_setabort()).

       ni_status ni_statistics(void *handle, ni_proplist *statistics)

	      Returns various statistics from the server.

       ni_status ni_write(void *handle, ni_id *dir, ni_proplist props)

	      Writes a new property list to the directory.

       ni_status ni_writename(void *handle, ni_id *dir,	 ni_index  prop_index,
       ni_index name_index, ni_name val)

	      Writes   a  new  property	 value	to  the	 property  indexed  by
	      prop_index and value indexed by val_index.

       ni_status ni_writeprop(void *handle, ni_id *dir,	 ni_index  prop_index,
       ni_namelist values)

	      Writes  a	 new value list to the property indexed by prop_index.
	      It is allowable to have more than one  property  with  the  same
	      name.

NeXT Computer, Inc.		August 29, 1989			   NETINFO(3N)
[top]
                             _         _         _ 
                            | |       | |       | |     
                            | |       | |       | |     
                         __ | | __ __ | | __ __ | | __  
                         \ \| |/ / \ \| |/ / \ \| |/ /  
                          \ \ / /   \ \ / /   \ \ / /   
                           \   /     \   /     \   /    
                            \_/       \_/       \_/ 
More information is available in HTML format for server OPENSTEP

List of man pages available for OPENSTEP

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net