1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
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
196
197
198
199
200
201
202
203
204
205
|
.\" Author: Juli Mallett <jmallett@FreeBSD.org>
.\" Date: June 04, 2003
.\" Description:
.\" Manual page for libufs functions:
.\" sbget(3)
.\" sbsearch(3)
.\" sbput(3)
.\" sbread(3)
.\" sbfind(3)
.\" sbwrite(3)
.\"
.\" This file is in the public domain.
.\"
.\" $FreeBSD$
.\"
.Dd August 8, 2022
.Dt SBREAD 3
.Os
.Sh NAME
.Nm sbget , sbsearch , sbput , sbread , sbfind , sbwrite
.Nd read and write superblocks of a UFS file system
.Sh LIBRARY
.Lb libufs
.Sh SYNOPSIS
.In sys/param.h
.In sys/mount.h
.In ufs/ufs/ufsmount.h
.In ufs/ufs/dinode.h
.In ufs/ffs/fs.h
.In libufs.h
.Ft int
.Fn sbget "int devfd" "struct fs **fsp" "off_t sblockloc" "int flags"
.Ft int
.Fn sbsearch "int devfd" "struct fs **fsp" "int flags"
.Ft int
.Fn sbput "int devfd" "struct fs *fs" "int numaltwrite"
.Ft int
.Fn sbread "struct uufsd *disk"
.Ft int
.Fn sbfind "struct uufsd *disk" "int flags"
.Ft int
.Fn sbwrite "struct uufsd *disk" "int all"
.Sh DESCRIPTION
The
.Fn sbget ,
.Fn sbsearch ,
.Fn sbread ,
and
.Fn sbfind
functions provide superblock reads for
.Xr libufs 3
consumers.
The
.Fn sbput
and
.Fn sbwrite
functions provide superblock writes for
.Xr libufs 3
consumers.
.Pp
The
.Fn sbget
and
.Fn sbsearch
functions first allocate a buffer to hold the superblock.
Using the
.Va devfd
file descriptor that references the filesystem disk,
.Fn sbget
reads the superblock located at the byte offset specified by
.Va sblockloc
into the allocated buffer.
The value
.Cm UFS_STDSB
may be specified for
.Va sblockloc
to request that the standard location for the superblock be read.
The
.Fn sbsearch
function uses the
.Va devfd
file descriptor that references the filesystem disk,
to search first for the superblock at the standard location.
If it is not found or is too damaged to use
.Fn sbsearch
will attempt to find one of the filesystem's alternate superblocks.
Flags are specified by
.Em or Ns 'ing
the following values:
.Pp
.Bl -tag -width UFS_NOCSUM
.It Cm UFS_NOCSUM
Causes only the superblock itself to be returned, but does not read in any
auxiliary data structures like the cylinder group summary information.
.It Cm UFS_NOMSG
Indicates that superblock inconsistency error messages should not be printed.
.El
.Pp
If successful,
.Fn sbget
and
.Fn sbsearch
functions return a pointer to the buffer containing the superblock in
.Va fsp .
The
.Fn sbget
and
.Fn sbsearch
functions are safe to use in threaded applications.
.Pp
The
.Fn sbput
function writes the superblock specified by
.Va fs
to the location from which it was read on the disk referenced by the
.Va devfd
file descriptor.
Additionally, the
.Fn sbput
function will update the first
.Va numaltwrite
alternate superblock locations.
To update all the alternate superblocks,
specify a
.Va numaltwrite
value of
.Va fs->fs_ncg .
The
.Fn sbput
function is safe to use in threaded applications.
Note that the
.Fn sbput
function needs to be called only if the superblock has been
modified and the on-disk copy needs to be updated.
.Pp
The
.Fn sbread
function reads the standard filesystem superblock.
The
.Fn sbfind
function tries to find a usable superblock.
It searchs first for the superblock at the standard location.
If it is not found or is too damaged to use
.Fn sbfind
will attempt to find one of the filesystem's alternate superblocks.
If successful
.Fn sbread
and
.Fn sbfind
return a superblock in the
.Va d_sb ,
structure embedded in the given user-land UFS disk structure.
.Pp
The
.Fn sbwrite
function writes the superblock from the
.Va d_sb ,
structure embedded in the given user-land UFS disk structure
to the location from which it was read.
Additionally, the
.Fn sbwrite
function will write to all the alternate superblock locations if the
.Fa all
value is non-zero.
.Sh RETURN VALUES
.Rv -std sbread sbwrite
The
.Fn sbget ,
.Fn sbsearch ,
and
.Fn sbput
functions return the value 0 if successful;
otherwise they return one of the errors described below.
.Sh ERRORS
The errors returned by
.Fn sbget ,
.Fn sbsearch ,
.Fn sbread ,
and
.Fn sbfind ,
include any of the errors specified for the library function
.Xr bread 3 .
Additionally, they may follow the
.Xr libufs 3
error methodologies in situations where no usable superblock could be
found.
.Pp
The errors returned by
.Fn sbput
and
.Fn sbwrite
include any of the errors specified for the library function
.Xr bwrite 3 .
.Sh SEE ALSO
.Xr bread 3 ,
.Xr bwrite 3 ,
.Xr libufs 3
.Sh HISTORY
These functions first appeared as part of
.Xr libufs 3
in
.Fx 5.0 .
.Sh AUTHORS
.An Juli Mallett Aq Mt jmallett@FreeBSD.org
.An Marshall Kirk McKusick Aq Mt mckusick@FreeBSD.org
|
