contrib/cvs-1.12/src/fileattr.h

   1 /* Declarations for file attribute munging features.
   2
   3    This program is free software; you can redistribute it and/or modify
   4    it under the terms of the GNU General Public License as published by
   5    the Free Software Foundation; either version 2, or (at your option)
   6    any later version.
   7
   8    This program is distributed in the hope that it will be useful,
   9    but WITHOUT ANY WARRANTY; without even the implied warranty of
  10    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  11    GNU General Public License for more details.  */
  12
  13 #ifndef FILEATTR_H
  14
  15 /* File containing per-file attributes.  The format of this file is in
  16    cvs.texinfo but here is a quick summary.  The file contains a
  17    series of entries:
  18
  19    ENT-TYPE FILENAME <tab> ATTRNAME = ATTRVAL
  20      {; ATTRNAME = ATTRVAL} <linefeed>
  21
  22    ENT-TYPE is 'F' for a file.
  23
  24    ENT-TYPE is 'D', and FILENAME empty, for default attributes.
  25
  26    Other ENT-TYPE are reserved for future expansion.
  27
  28    Note that the order of the line is not significant; CVS is free to
  29    rearrange them at its convenience.
  30
  31    FIXME: this implementation doesn't handle '\0' in any of the
  32    fields.  We are encouraged to fix this (by cvs.texinfo).
  33
  34    By convention, ATTRNAME starting with '_' is for an attribute given
  35    special meaning by CVS; other ATTRNAMEs are for user-defined attributes
  36    (or will be, once we add commands to manipulate user-defined attributes).
  37
  38    Builtin attributes:
  39
  40    _watched: Present means the file is watched and should be checked out
  41    read-only.
  42
  43    _watchers: Users with watches for this file.  Value is
  44    WATCHER > TYPE { , WATCHER > TYPE }
  45    where WATCHER is a username, and TYPE is edit,unedit,commit separated by
  46    + (or nothing if none; there is no "none" or "all" keyword).
  47
  48    _editors: Users editing this file.  Value is
  49    EDITOR > VAL { , EDITOR > VAL }
  50    where EDITOR is a username, and VAL is TIME+HOSTNAME+PATHNAME, where
  51    TIME is when the "cvs edit" command happened,
  52    and HOSTNAME and PATHNAME are for the working directory.  */
  53
  54 #define CVSREP_FILEATTR "CVS/fileattr"
  55
  56 /* Prepare for a new directory with repository REPOS.  If REPOS is NULL,
  57    then prepare for a "non-directory"; the caller can call fileattr_write
  58    and fileattr_free, but must not call fileattr_get or fileattr_set.  */
  59 extern void fileattr_startdir (const char *repos);
  60
  61 /* Get the attribute ATTRNAME for file FILENAME.  The return value
  62    points into memory managed by the fileattr_* routines, should not
  63    be altered by the caller, and is only good until the next call to
  64    fileattr_clear or fileattr_set.  It points to the value, terminated
  65    by '\0' or ';'.  Return NULL if said file lacks said attribute.
  66    If FILENAME is NULL, return default attributes (attributes for
  67    files created in the future).  */
  68 extern char *fileattr_get (const char *filename, const char *attrname);
  69
  70 /* Like fileattr_get, but return a pointer to a newly malloc'd string
  71    terminated by '\0' (or NULL if said file lacks said attribute).  */
  72 extern char *fileattr_get0 (const char *filename,
  73                                    const char *attrname);
  74
  75 /* This is just a string manipulation function; it does not manipulate
  76    file attributes as such.
  77
  78    LIST is in the format
  79
  80    ATTRNAME NAMEVALSEP ATTRVAL {ENTSEP ATTRNAME NAMEVALSEP ATTRVAL}
  81
  82    And we want to put in an attribute with name NAME and value VAL,
  83    replacing the already-present attribute with name NAME if there is
  84    one.  Or if VAL is NULL remove attribute NAME.  Return a new
  85    malloc'd list; don't muck with the one passed in.  If we are removing
  86    the last attribute return NULL.  LIST can be NULL to mean that we
  87    started out without any attributes.
  88
  89    Examples:
  90
  91    fileattr_modify ("abc=def", "xxx", "val", '=', ';')) => "abc=def;xxx=val"
  92    fileattr_modify ("abc=def", "abc", "val", '=', ';')) => "abc=val"
  93    fileattr_modify ("abc=v1;def=v2", "abc", "val", '=', ';'))
  94      => "abc=val;def=v2"
  95    fileattr_modify ("abc=v1;def=v2", "def", "val", '=', ';'))
  96      => "abc=v1;def=val"
  97    fileattr_modify ("abc=v1;def=v2", "xxx", "val", '=', ';'))
  98      => "abc=v1;def=v2;xxx=val"
  99    fileattr_modify ("abc=v1;def=v2;ghi=v3", "def", "val", '=', ';'))
 100      => "abc=v1;def=val;ghi=v3"
 101 */
 102
 103 extern char *fileattr_modify (char *list, const char *attrname,
 104                                      const char *attrval, int namevalsep,
 105                                      int entsep);
 106
 107 /* Set attribute ATTRNAME for file FILENAME to ATTRVAL.  If ATTRVAL is NULL,
 108    the attribute is removed.  Changes are not written to disk until the
 109    next call to fileattr_write.  If FILENAME is NULL, set attributes for
 110    files created in the future.  If ATTRVAL is NULL, remove that attribute.  */
 111 extern void fileattr_set (const char *filename, const char *attrname,
 112                                  const char *attrval);
 113
 114 /* Get all the attributes for file FILENAME.  They are returned as malloc'd
 115    data in an unspecified format which is guaranteed only to be good for
 116    passing to fileattr_setall, or NULL if no attributes.  If FILENAME is
 117    NULL, get default attributes.  */
 118 extern char *fileattr_getall (const char *filename);
 119
 120 /* Set the attributes for file FILENAME to ATTRS, overwriting all previous
 121    attributes for that file.  ATTRS was obtained from a previous call to
 122    fileattr_getall (malloc'd data or NULL).  */
 123 extern void fileattr_setall (const char *filename, const char *attrs);
 124
 125 /* Set the attributes for file FILENAME in whatever manner is appropriate
 126    for a newly created file.  */
 127 extern void fileattr_newfile (const char *filename);
 128
 129 /* Write out all modified attributes.  */
 130 extern void fileattr_write (void);
 131
 132 /* Free all memory allocated by fileattr_*.  */
 133 extern void fileattr_free (void);
 134
 135 #define FILEATTR_H 1
 136 #endif /* fileattr.h */