sha1_file.c: document a bunch of functions defined in the file
Signed-off-by: Michael Haggerty <mhagger@alum.mit.edu> Acked-by: Nicolas Pitre <nico@fluxnic.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Michael Haggerty committed
Feb 21, 2014 at 17:32 UTC
d40d535b892bf6991811f94ee91f459fc3ea2648
2 files changed
+78
-14
cache.h
+63
-3
@@ -659,9 +659,28 @@ extern char *git_path(const char *fmt, ...) __attribute__((format (printf, 1, 2)
659
extern char *git_path_submodule(const char *path, const char *fmt, ...)
660
__attribute__((format (printf, 2, 3)));
661
662
+/*
663
+ * Return the name of the file in the local object database that would
664
+ * be used to store a loose object with the specified sha1. The
665
+ * return value is a pointer to a statically allocated buffer that is
666
+ * overwritten each time the function is called.
667
+ */
668
extern const char *sha1_file_name(const unsigned char *sha1);
669
+
670
+/*
671
+ * Return the name of the (local) packfile with the specified sha1 in
672
+ * its name. The return value is a pointer to memory that is
673
+ * overwritten each time this function is called.
674
+ */
675
extern char *sha1_pack_name(const unsigned char *sha1);
676
+
677
+/*
678
+ * Return the name of the (local) pack index file with the specified
679
+ * sha1 in its name. The return value is a pointer to memory that is
680
+ * overwritten each time this function is called.
681
+ */
682
extern char *sha1_pack_index_name(const unsigned char *sha1);
683
+
684
extern const char *find_unique_abbrev(const unsigned char *sha1, int);
685
extern const unsigned char null_sha1[20];
686
@@ -820,7 +839,19 @@ extern int check_sha1_signature(const unsigned char *sha1, void *buf, unsigned l
839
extern int move_temp_to_file(const char *tmpfile, const char *filename);
840
841
extern int has_sha1_pack(const unsigned char *sha1);
842
+
843
+/*
844
+ * Return true iff we have an object named sha1, whether local or in
845
+ * an alternate object database, and whether packed or loose. This
846
+ * function does not respect replace references.
847
+ */
848
extern int has_sha1_file(const unsigned char *sha1);
849
+
850
+/*
851
+ * Return true iff an alternate object database has a loose object
852
+ * with the specified name. This function does not respect replace
853
+ * references.
854
+ */
855
extern int has_loose_object_nonlocal(const unsigned char *sha1);
856
857
extern int has_pack_index(const unsigned char *sha1);
@@ -1083,17 +1114,46 @@ extern struct packed_git *find_sha1_pack(const unsigned char *sha1,
1114
struct packed_git *packs);
1115
1116
extern void pack_report(void);
1117
+
1118
+/*
1119
+ * mmap the index file for the specified packfile (if it is not
1120
+ * already mmapped). Return 0 on success.
1121
+ */
1122
extern int open_pack_index(struct packed_git *);
1123
+
1124
+/*
1125
+ * munmap the index file for the specified packfile (if it is
1126
+ * currently mmapped).
1127
+ */
1128
extern void close_pack_index(struct packed_git *);
1129
+
1130
extern unsigned char *use_pack(struct packed_git *, struct pack_window **, off_t, unsigned long *);
1131
extern void close_pack_windows(struct packed_git *);
1132
extern void unuse_pack(struct pack_window **);
1133
extern void free_pack_by_name(const char *);
1134
extern void clear_delta_base_cache(void);
1135
extern struct packed_git *add_packed_git(const char *, int, int);
1094
-extern const unsigned char *nth_packed_object_sha1(struct packed_git *, uint32_t);
1095
-extern off_t nth_packed_object_offset(const struct packed_git *, uint32_t);
1096
-extern off_t find_pack_entry_one(const unsigned char *, struct packed_git *);
1136
+
1137
+/*
1138
+ * Return the SHA-1 of the nth object within the specified packfile.
1139
+ * Open the index if it is not already open. The return value points
1140
+ * at the SHA-1 within the mmapped index. Return NULL if there is an
1141
+ * error.
1142
+ */
1143
+extern const unsigned char *nth_packed_object_sha1(struct packed_git *, uint32_t n);
1144
+
1145
+/*
1146
+ * Return the offset of the nth object within the specified packfile.
1147
+ * The index must already be opened.
1148
+ */
1149
+extern off_t nth_packed_object_offset(const struct packed_git *, uint32_t n);
1150
+
1151
+/*
1152
+ * If the object named sha1 is present in the specified packfile,
1153
+ * return its offset within the packfile; otherwise, return 0.
1154
+ */
1155
+extern off_t find_pack_entry_one(const unsigned char *sha1, struct packed_git *);
1156
+
1157
extern int is_pack_valid(struct packed_git *);
1158
extern void *unpack_entry(struct packed_git *, off_t, enum object_type *, unsigned long *);
1159
extern unsigned long unpack_object_header_buffer(const unsigned char *buf, unsigned long len, enum object_type *type, unsigned long *sizep);
sha1_file.c
+15
-11
@@ -184,16 +184,6 @@ static void fill_sha1_path(char *pathbuf, const unsigned char *sha1)
184
}
185
}
186
187
-/*
188
- * NOTE! This returns a statically allocated buffer, so you have to be
189
- * careful about using it. Do an "xstrdup()" if you need to save the
190
- * filename.
191
- *
192
- * Also note that this returns the location for creating. Reading
193
- * SHA1 file can happen from any alternate directory listed in the
194
- * DB_ENVIRONMENT environment variable if it is not found in
195
- * the primary object database.
196
- */
187
const char *sha1_file_name(const unsigned char *sha1)
188
{
189
static char buf[PATH_MAX];
@@ -214,6 +204,11 @@ const char *sha1_file_name(const unsigned char *sha1)
204
return buf;
205
}
206
207
+/*
208
+ * Return the name of the pack or index file with the specified sha1
209
+ * in its filename. *base and *name are scratch space that must be
210
+ * provided by the caller. which should be "pack" or "idx".
211
+ */
212
static char *sha1_get_pack_name(const unsigned char *sha1,
213
char **name, char **base, const char *which)
214
{
@@ -496,7 +491,12 @@ void pack_report(void)
491
sz_fmt(pack_mapped), sz_fmt(peak_pack_mapped));
492
}
493
499
-static int check_packed_git_idx(const char *path, struct packed_git *p)
494
+/*
495
+ * Open and mmap the index file at path, perform a couple of
496
+ * consistency checks, then record its information to p. Return 0 on
497
+ * success.
498
+ */
499
+static int check_packed_git_idx(const char *path, struct packed_git *p)
500
{
501
void *idx_map;
502
struct pack_idx_header *hdr;
@@ -2449,6 +2449,10 @@ static int fill_pack_entry(const unsigned char *sha1,
2449
return 1;
2450
}
2451
2452
+/*
2453
+ * Iff a pack file contains the object named by sha1, return true and
2454
+ * store its location to e.
2455
+ */
2456
static int find_pack_entry(const unsigned char *sha1, struct pack_entry *e)
2457
{
2458
struct packed_git *p;