lib/libufs/ufs_disk_close.3

   1 .\" Author:     Juli Mallett <jmallett@FreeBSD.org>
   2 .\" Date:       June 04, 2003
   3 .\" Description:
   4 .\"     Manual page for libufs functions:
   5 .\"             ufs_disk_close(3)
   6 .\"             ufs_disk_fillout(3)
   7 .\"             ufs_disk_fillout_blank(3)
   8 .\"             ufs_disk_write(3)
   9 .\"
  10 .\" This file is in the public domain.
  11 .\"
  12 .Dd November 17, 2023
  13 .Dt UFS_DISK_CLOSE 3
  14 .Os
  15 .Sh NAME
  16 .Nm ufs_disk_close ,
  17 .Nm ufs_disk_fillout ,
  18 .Nm ufs_disk_fillout_blank ,
  19 .Nm ufs_disk_write
  20 .Nd open and close userland UFS disks
  21 .Sh LIBRARY
  22 .Lb libufs
  23 .Sh SYNOPSIS
  24 .In sys/param.h
  25 .In sys/mount.h
  26 .In ufs/ufs/ufsmount.h
  27 .In ufs/ufs/dinode.h
  28 .In ufs/ffs/fs.h
  29 .In libufs.h
  30 .Ft int
  31 .Fn ufs_disk_close "struct uufsd *disk"
  32 .Ft int
  33 .Fn ufs_disk_fillout "struct uufsd *disk" "const char *name"
  34 .Ft int
  35 .Fn ufs_disk_fillout_blank "struct uufsd *disk" "const char *name"
  36 .Ft int
  37 .Fn ufs_disk_write "struct uufsd *disk"
  38 .Sh DESCRIPTION
  39 The
  40 .Fn ufs_disk_close
  41 function closes a disk and frees internal memory related to it.
  42 It does not free the
  43 .Fa disk
  44 structure.
  45 .Pp
  46 The
  47 .Fn ufs_disk_fillout
  48 and
  49 .Fn ufs_disk_fillout_blank
  50 functions open a disk specified by
  51 .Fa name
  52 and populate the structure pointed to by
  53 .Fa disk .
  54 The structure referenced by the
  55 .Fa disk
  56 pointer must be aligned to at least the alignment specified by
  57 .Dv LIBUFS_ALIGN
  58 that is defined in the
  59 .Lb libufs.h
  60 header file.
  61 The disk is opened read-only.
  62 The specified
  63 .Fa name
  64 may be either a mountpoint, a device name or a filesystem image.
  65 The
  66 .Fn ufs_disk_fillout
  67 function assumes there is a valid superblock and will fail if not,
  68 whereas the
  69 .Fn ufs_disk_fillout_blank
  70 function makes no assumptions of that sort.
  71 .Pp
  72 The
  73 .Fn ufs_disk_write
  74 function attempts to re-open a disk as writable if it is not currently.
  75 .Sh ERRORS
  76 The function
  77 .Fn ufs_disk_close
  78 has no failure points.
  79 .Pp
  80 The function
  81 .Fn ufs_disk_fillout
  82 may fail for any of the reasons
  83 .Fn ufs_disk_fillout_blank
  84 might, as well as for any reason
  85 .Xr sbread 3
  86 might.
  87 .Pp
  88 The
  89 .Fn ufs_disk_fillout_blank
  90 may fail and set
  91 .Va errno
  92 for any of the errors specified for the library functions
  93 .Xr open 2 ,
  94 .Xr strdup 3 .
  95 Additionally, it may follow the
  96 .Xr libufs 3
  97 error methodologies in situations where no device could be found to
  98 open.
  99 .Pp
 100 The function
 101 .Fn ufs_disk_write
 102 may fail and set
 103 .Va errno
 104 for any of the errors specified for the library functions
 105 .Xr open 2
 106 and
 107 .Xr stat 2 .
 108 Namely, it will fail if the disk in question may not be written to.
 109 .Sh SEE ALSO
 110 .Xr open 2 ,
 111 .Xr getfsfile 3 ,
 112 .Xr libufs 3 ,
 113 .Xr sbread 3
 114 .Sh HISTORY
 115 These functions first appeared as part of
 116 .Xr libufs 3
 117 in
 118 .Fx 5.0 .
 119 .Sh AUTHORS
 120 .An Juli Mallett Aq Mt jmallett@FreeBSD.org