update changelog
[alioth/cvs.git] / 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 */