lib/libc/sys/kldstat.2

   1 .\"
   2 .\" Copyright (c) 1999 Chris Costello
   3 .\" All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\"
  14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  17 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  18 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  20 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  22 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  24 .\" SUCH DAMAGE.
  25 .\"
  26 .\" $FreeBSD$
  27 .\"
  28 .Dd March 28, 2012
  29 .Dt KLDSTAT 2
  30 .Os
  31 .Sh NAME
  32 .Nm kldstat
  33 .Nd get status of kld file
  34 .Sh LIBRARY
  35 .Lb libc
  36 .Sh SYNOPSIS
  37 .In sys/param.h
  38 .In sys/linker.h
  39 .Ft int
  40 .Fn kldstat "int fileid" "struct kld_file_stat *stat"
  41 .Sh DESCRIPTION
  42 The
  43 .Fn kldstat
  44 system call writes the info for the file referred to by
  45 .Fa fileid
  46 into
  47 .Fa stat .
  48 .Bd -literal
  49 struct kld_file_stat {
  50         int         version;    /* set to sizeof(struct kld_file_stat) */
  51         char        name[MAXPATHLEN];
  52         int         refs;
  53         int         id;
  54         caddr_t     address;
  55         size_t      size;
  56         char        pathname[MAXPATHLEN];
  57 };
  58 .Ed
  59 .Bl -tag -width XXXaddress
  60 .It version
  61 This field is set to the size of the structure mentioned above by the code
  62 calling
  63 .Fn kldstat ,
  64 and not
  65 .Fn kldstat
  66 itself.
  67 .It name
  68 The name of the file referred to by
  69 .Fa fileid .
  70 .It refs
  71 The number of modules referenced by
  72 .Fa fileid .
  73 .It id
  74 The id of the file specified in
  75 .Fa fileid .
  76 .It address
  77 The load address of the kld file.
  78 .It size
  79 The amount of memory in bytes allocated by the file.
  80 .It pathname
  81 The full name of the file referred to by
  82 .Fa fileid ,
  83 including the path.
  84 .El
  85 .Sh RETURN VALUES
  86 .Rv -std kldstat
  87 .Sh ERRORS
  88 The information for the file referred to by
  89 .Fa fileid
  90 is filled into the structure pointed to by
  91 .Fa stat
  92 unless:
  93 .Bl -tag -width Er
  94 .It Bq Er ENOENT
  95 The file was not found (probably not loaded).
  96 .It Bq Er EINVAL
  97 The version specified in the
  98 .Fa version
  99 field of stat is not the proper version.
 100 You would need to rebuild world, the
 101 kernel, or your application, if this error occurs, given that you did properly
 102 fill in the
 103 .Fa version
 104 field.
 105 .It Bq Er EFAULT
 106 There was a problem copying one, some, or all of the fields into
 107 .Fa stat
 108 in the
 109 .Xr copyout 9
 110 function.
 111 .El
 112 .Sh SEE ALSO
 113 .Xr kldfind 2 ,
 114 .Xr kldfirstmod 2 ,
 115 .Xr kldload 2 ,
 116 .Xr kldnext 2 ,
 117 .Xr kldsym 2 ,
 118 .Xr kldunload 2 ,
 119 .Xr modfind 2 ,
 120 .Xr modfnext 2 ,
 121 .Xr modnext 2 ,
 122 .Xr modstat 2 ,
 123 .Xr kld 4 ,
 124 .Xr kldstat 8
 125 .Sh HISTORY
 126 The
 127 .Nm kld
 128 interface first appeared in
 129 .Fx 3.0 .
 130 .Sh BUGS
 131 The pathname may not be accurate if the file system mounts have
 132 changed since the module was loaded, or if this function is called
 133 within a chrooted environment.