home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3c / getut.z / getut
Encoding:
Text File  |  2002-10-03  |  16.5 KB  |  199 lines
  1.  
  2.  
  3.  
  4. ggggeeeettttuuuutttt((((3333CCCC))))                                                            ggggeeeettttuuuutttt((((3333CCCC))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      _gggg_eeee_tttt_uuuu_tttt: _gggg_eeee_tttt_uuuu_tttt_eeee_nnnn_tttt, _gggg_eeee_tttt_uuuu_tttt_iiii_dddd, _gggg_eeee_tttt_uuuu_tttt_llll_iiii_nnnn_eeee, _pppp_uuuu_tttt_uuuu_tttt_llll_iiii_nnnn_eeee, _ssss_eeee_tttt_uuuu_tttt_eeee_nnnn_tttt, _eeee_nnnn_dddd_uuuu_tttt_eeee_nnnn_tttt,
  10.      _uuuu_tttt_mmmm_pppp_nnnn_aaaa_mmmm_eeee - access _uuuu_tttt_mmmm_pppp file entry
  11.  
  12. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  13.      _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_uuuu_tttt_mmmm_pppp_...._hhhh_>>>>
  14.  
  15.      _ssss_tttt_rrrr_uuuu_cccc_tttt _uuuu_tttt_mmmm_pppp _****_gggg_eeee_tttt_uuuu_tttt_eeee_nnnn_tttt _((((_vvvv_oooo_iiii_dddd_))))_;;;;
  16.  
  17.      _ssss_tttt_rrrr_uuuu_cccc_tttt _uuuu_tttt_mmmm_pppp _****_gggg_eeee_tttt_uuuu_tttt_iiii_dddd _((((_cccc_oooo_nnnn_ssss_tttt _ssss_tttt_rrrr_uuuu_cccc_tttt _uuuu_tttt_mmmm_pppp _****_iiii_dddd_))))_;;;;
  18.  
  19.      _ssss_tttt_rrrr_uuuu_cccc_tttt _uuuu_tttt_mmmm_pppp _****_gggg_eeee_tttt_uuuu_tttt_llll_iiii_nnnn_eeee _((((_cccc_oooo_nnnn_ssss_tttt _ssss_tttt_rrrr_uuuu_cccc_tttt _uuuu_tttt_mmmm_pppp _****_llll_iiii_nnnn_eeee_))))_;;;;
  20.  
  21.      _ssss_tttt_rrrr_uuuu_cccc_tttt _uuuu_tttt_mmmm_pppp _****_pppp_uuuu_tttt_uuuu_tttt_llll_iiii_nnnn_eeee _((((_cccc_oooo_nnnn_ssss_tttt _ssss_tttt_rrrr_uuuu_cccc_tttt _uuuu_tttt_mmmm_pppp _****_uuuu_tttt_mmmm_pppp_))))_;;;;
  22.  
  23.      _vvvv_oooo_iiii_dddd _ssss_eeee_tttt_uuuu_tttt_eeee_nnnn_tttt _((((_vvvv_oooo_iiii_dddd_))))_;;;;
  24.  
  25.      _vvvv_oooo_iiii_dddd _eeee_nnnn_dddd_uuuu_tttt_eeee_nnnn_tttt _((((_vvvv_oooo_iiii_dddd_))))_;;;;
  26.  
  27.      _iiii_nnnn_tttt _uuuu_tttt_mmmm_pppp_nnnn_aaaa_mmmm_eeee _((((_cccc_oooo_nnnn_ssss_tttt _cccc_hhhh_aaaa_rrrr _****_ffff_iiii_llll_eeee_))))_;;;;
  28.  
  29. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  30.      NNNNOOOOTTTTEEEE:::: these routines are all obsolete and are provided for backward
  31.      compatibility only.  All access to or modification of these files must be
  32.      done via the _gggg_eeee_tttt_uuuu_tttt_xxxx(3C) set of interfaces.
  33.  
  34.      _gggg_eeee_tttt_uuuu_tttt_eeee_nnnn_tttt, _gggg_eeee_tttt_uuuu_tttt_iiii_dddd, _gggg_eeee_tttt_uuuu_tttt_llll_iiii_nnnn_eeee, and _pppp_uuuu_tttt_uuuu_tttt_llll_iiii_nnnn_eeee each return a pointer to a
  35.      _uuuu_tttt_mmmm_pppp structure:
  36.  
  37.           _ssss_tttt_rrrr_uuuu_cccc_tttt _uuuu_tttt_mmmm_pppp _{{{{
  38.                _cccc_hhhh_aaaa_rrrr     _uuuu_tttt______uuuu_ssss_eeee_rrrr_[[[[_8888_]]]]_;;;;      _////_**** _uuuu_ssss_eeee_rrrr _llll_oooo_gggg_iiii_nnnn _nnnn_aaaa_mmmm_eeee _****_////
  39.                _cccc_hhhh_aaaa_rrrr     _uuuu_tttt______iiii_dddd_[[[[_4444_]]]]_;;;;        _////_**** _////_eeee_tttt_cccc_////_iiii_nnnn_iiii_tttt_tttt_aaaa_bbbb _iiii_dddd _((((_uuuu_ssss_uuuu_aaaa_llll_llll_yyyy _llll_iiii_nnnn_eeee_####_)))) _****_////
  40.                _cccc_hhhh_aaaa_rrrr     _uuuu_tttt______llll_iiii_nnnn_eeee_[[[[_1111_2222_]]]]_;;;;     _////_**** _dddd_eeee_vvvv_iiii_cccc_eeee _nnnn_aaaa_mmmm_eeee _((((_cccc_oooo_nnnn_ssss_oooo_llll_eeee_,,,, _llll_nnnn_xxxx_xxxx_)))) _****_////
  41.                _ssss_hhhh_oooo_rrrr_tttt    _uuuu_tttt______pppp_iiii_dddd_;;;;          _////_**** _pppp_rrrr_oooo_cccc_eeee_ssss_ssss _iiii_dddd _****_////
  42.                _ssss_hhhh_oooo_rrrr_tttt    _uuuu_tttt______tttt_yyyy_pppp_eeee_;;;;         _////_**** _tttt_yyyy_pppp_eeee _oooo_ffff _eeee_nnnn_tttt_rrrr_yyyy _****_////
  43.                _ssss_tttt_rrrr_uuuu_cccc_tttt   _eeee_xxxx_iiii_tttt______ssss_tttt_aaaa_tttt_uuuu_ssss _{{{{
  44.                    _ssss_hhhh_oooo_rrrr_tttt    _eeee______tttt_eeee_rrrr_mmmm_iiii_nnnn_aaaa_tttt_iiii_oooo_nnnn_;;;;    _////_**** _tttt_eeee_rrrr_mmmm_iiii_nnnn_aaaa_tttt_iiii_oooo_nnnn _ssss_tttt_aaaa_tttt_uuuu_ssss _****_////
  45.                    _ssss_hhhh_oooo_rrrr_tttt    _eeee______eeee_xxxx_iiii_tttt_;;;;           _////_**** _eeee_xxxx_iiii_tttt _ssss_tttt_aaaa_tttt_uuuu_ssss _****_////
  46.                _}}}} _uuuu_tttt______eeee_xxxx_iiii_tttt_;;;;                _////_**** _eeee_xxxx_iiii_tttt _ssss_tttt_aaaa_tttt_uuuu_ssss _oooo_ffff _aaaa _pppp_rrrr_oooo_cccc_eeee_ssss_ssss _mmmm_aaaa_rrrr_kkkk_eeee_dddd _****_////
  47.                                          _////_**** _aaaa_ssss _DDDD_EEEE_AAAA_DDDD______PPPP_RRRR_OOOO_CCCC_EEEE_SSSS_SSSS _****_////
  48.                _tttt_iiii_mmmm_eeee______tttt   _uuuu_tttt______tttt_iiii_mmmm_eeee_;;;;         _////_**** _tttt_iiii_mmmm_eeee _eeee_nnnn_tttt_rrrr_yyyy _wwww_aaaa_ssss _mmmm_aaaa_dddd_eeee _****_////
  49.           _}}}}_;;;;
  50.  
  51.      _gggg_eeee_tttt_uuuu_tttt_eeee_nnnn_tttt reads the next entry from a _uuuu_tttt_mmmm_pppp-like file.  If the file is not
  52.      already open, it opens it.  If it reaches the end of the file, it fails.
  53.  
  54.      _gggg_eeee_tttt_uuuu_tttt_iiii_dddd searches forward from the last entry read or, if no entries have
  55.      been read, from the first entry in the _uuuu_tttt_mmmm_pppp file until it finds an entry
  56.      with a _u_t__t_y_p_e matching _iiii_dddd->ut_type if the type specified is _RRRR_UUUU_NNNN______LLLL_VVVV_LLLL,
  57.      _BBBB_OOOO_OOOO_TTTT______TTTT_IIII_MMMM_EEEE, _OOOO_LLLL_DDDD______TTTT_IIII_MMMM_EEEE, or _NNNN_EEEE_WWWW______TTTT_IIII_MMMM_EEEE.  If the type specified in _iiii_dddd is
  58.      _IIII_NNNN_IIII_TTTT______PPPP_RRRR_OOOO_CCCC_EEEE_SSSS_SSSS, _LLLL_OOOO_GGGG_IIII_NNNN______PPPP_RRRR_OOOO_CCCC_EEEE_SSSS_SSSS, _UUUU_SSSS_EEEE_RRRR______PPPP_RRRR_OOOO_CCCC_EEEE_SSSS_SSSS, or _DDDD_EEEE_AAAA_DDDD______PPPP_RRRR_OOOO_CCCC_EEEE_SSSS_SSSS, then _gggg_eeee_tttt_uuuu_tttt_iiii_dddd
  59.      will return a pointer to the first entry whose type is one of these four
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. ggggeeeettttuuuutttt((((3333CCCC))))                                                            ggggeeeettttuuuutttt((((3333CCCC))))
  71.  
  72.  
  73.  
  74.      and whose _uuuu_tttt______iiii_dddd field matches _iiii_dddd->ut_id.  If the end of file is reached
  75.      without a match, it fails.
  76.  
  77.      _gggg_eeee_tttt_uuuu_tttt_llll_iiii_nnnn_eeee searches forward from the last entry read or, if no entries
  78.      have been read, from the first entry in the _uuuu_tttt_mmmm_pppp file until it finds an
  79.      entry of the type _LLLL_OOOO_GGGG_IIII_NNNN______PPPP_RRRR_OOOO_CCCC_EEEE_SSSS_SSSS or _UUUU_SSSS_EEEE_RRRR______PPPP_RRRR_OOOO_CCCC_EEEE_SSSS_SSSS that also has a _u_t__l_i_n_e
  80.      string matching the _llll_iiii_nnnn_eeee->ut_line string.  If the end of file is reached
  81.      without a match, it fails.
  82.  
  83.      _pppp_uuuu_tttt_uuuu_tttt_llll_iiii_nnnn_eeee writes the supplied _uuuu_tttt_mmmm_pppp structure into the _uuuu_tttt_mmmm_pppp file.  It uses
  84.      _gggg_eeee_tttt_uuuu_tttt_iiii_dddd to search forward for the proper place if it finds that it is not
  85.      already there.  It is expected that normally the user of _pppp_uuuu_tttt_uuuu_tttt_llll_iiii_nnnn_eeee will
  86.      have searched for the proper entry using one of the _gggg_eeee_tttt_uuuu_tttt routines.  If
  87.      so, _pppp_uuuu_tttt_uuuu_tttt_llll_iiii_nnnn_eeee will not search.  If _pppp_uuuu_tttt_uuuu_tttt_llll_iiii_nnnn_eeee does not find a matching
  88.      slot for the new entry, it will add a new entry to the end of the file.
  89.      It returns a pointer to the _uuuu_tttt_mmmm_pppp structure.
  90.  
  91.      _ssss_eeee_tttt_uuuu_tttt_eeee_nnnn_tttt resets the input stream to the beginning of the file.  This
  92.      reset should be done before each search for a new entry if it is desired
  93.      that the entire file be examined.
  94.  
  95.      _eeee_nnnn_dddd_uuuu_tttt_eeee_nnnn_tttt closes the currently open file.
  96.  
  97.      _uuuu_tttt_mmmm_pppp_nnnn_aaaa_mmmm_eeee allows the user to change the name of the file examined, from
  98.      _////_vvvv_aaaa_rrrr_////_aaaa_dddd_mmmm_////_uuuu_tttt_mmmm_pppp to any other file.  It is most often expected that this
  99.      other file will be _////_vvvv_aaaa_rrrr_////_aaaa_dddd_mmmm_////_wwww_tttt_mmmm_pppp.  If the file does not exist, this will
  100.      not be apparent until the first attempt to reference the file is made.
  101.      _uuuu_tttt_mmmm_pppp_nnnn_aaaa_mmmm_eeee does not open the file.  It just closes the old file if it is
  102.      currently open and saves the new file name.  If the file name given is
  103.      longer than 79 characters, _uuuu_tttt_mmmm_pppp_nnnn_aaaa_mmmm_eeee returns 0.  Otherwise, it returns 1.
  104.  
  105. FFFFIIIILLLLEEEESSSS
  106.      _////_vvvv_aaaa_rrrr_////_aaaa_dddd_mmmm_////_uuuu_tttt_mmmm_pppp
  107.      _////_vvvv_aaaa_rrrr_////_aaaa_dddd_mmmm_////_wwww_tttt_mmmm_pppp
  108.  
  109. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  110.      _gggg_eeee_tttt_uuuu_tttt_xxxx(3C), _tttt_tttt_yyyy_ssss_llll_oooo_tttt(3C), _uuuu_tttt_mmmm_pppp(4), _uuuu_tttt_mmmm_pppp_xxxx(4).
  111.  
  112. DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS
  113.      A null pointer is returned upon failure to read, whether for permissions
  114.      or having reached the end of file, or upon failure to write.
  115.  
  116. WWWWAAAARRRRNNNNIIIINNNNGGGG
  117.      All changes to _////_vvvv_aaaa_rrrr_////_aaaa_dddd_mmmm_////_wwww_tttt_mmmm_pppp must also be logged in _////_vvvv_aaaa_rrrr_////_aaaa_dddd_mmmm_////_wwww_tttt_mmmm_pppp_xxxx.  Most
  118.      commands that extract information from these files silently discard all
  119.      _wwww_tttt_mmmm_pppp_xxxx entries without corresponding _wwww_tttt_mmmm_pppp entries.
  120.  
  121.      These routines all assume the existence of "_u_t_m_p_x" like file.  Many won't
  122.      function properly unless such a file exists.
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. ggggeeeettttuuuutttt((((3333CCCC))))                                                            ggggeeeettttuuuutttt((((3333CCCC))))
  137.  
  138.  
  139.  
  140. NNNNOOOOTTTTEEEESSSS
  141.      The most current entry is saved in a static structure.  Multiple accesses
  142.      require that it be copied before further accesses are made.  On each call
  143.      to either _gggg_eeee_tttt_uuuu_tttt_iiii_dddd or _gggg_eeee_tttt_uuuu_tttt_llll_iiii_nnnn_eeee, the routine examines the static structure
  144.      before performing more I/O.  If the contents of the static structure
  145.      match what it is searching for, it looks no further.  For this reason, to
  146.      use _gggg_eeee_tttt_uuuu_tttt_llll_iiii_nnnn_eeee to search for multiple occurrences, it would be necessary
  147.      to zero out the static area after each success, or _gggg_eeee_tttt_uuuu_tttt_llll_iiii_nnnn_eeee would just
  148.      return the same structure over and over again.  There is one exception to
  149.      the rule about emptying the structure before further reads are done.  The
  150.      implicit read done by _pppp_uuuu_tttt_uuuu_tttt_llll_iiii_nnnn_eeee (if it finds that it is not already at
  151.      the correct place in the file) will not alter the contents of the static
  152.      structure returned by the _gggg_eeee_tttt_uuuu_tttt_eeee_nnnn_tttt, _gggg_eeee_tttt_uuuu_tttt_iiii_dddd or _gggg_eeee_tttt_uuuu_tttt_llll_iiii_nnnn_eeee routines, if the
  153.      user has just modified those contents and passed the pointer back to
  154.      _pppp_uuuu_tttt_uuuu_tttt_llll_iiii_nnnn_eeee.
  155.  
  156.      _gggg_eeee_tttt_uuuu_tttt_eeee_nnnn_tttt, _gggg_eeee_tttt_uuuu_tttt_iiii_dddd, _gggg_eeee_tttt_uuuu_tttt_llll_iiii_nnnn_eeee, and _pppp_uuuu_tttt_uuuu_tttt_llll_iiii_nnnn_eeee, place file locks on files
  157.      used during function execution. File locks are not held across calls to
  158.      these or other functions, but signals may interrupt the execution of
  159.      these functions allowing file locks to be held. When using these
  160.      functions where a signal may interrupt function execution, _eeee_nnnn_dddd_uuuu_tttt_eeee_nnnn_tttt
  161.      should be called by signal handlers to release any file locks acquired by
  162.      an interrupted function.
  163.  
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.