github.com/szmcdull/go-forceexport@v0.0.0-20230908151957-3dac42f564da/README.md (about)

     1  # go-forceexport
     2  
     3  go-forceexport is a golang package that allows access to any module-level
     4  function, even ones that are not exported. You give it the string name of a
     5  function , like `"time.now"`, and gives you a function value that calls that
     6  function. More generally, it can be used to achieve something like reflection on
     7  top-level functions, whereas the `reflect` package only lets you access methods
     8  by name.
     9  
    10  As you might expect, this library is **unsafe** and **fragile** and probably
    11  shouldn't be used in production. See "Use cases and pitfalls" below.
    12  
    13  It has only been tested on Mac OS X with Go 1.6. If you find that it works or
    14  breaks on other platforms, feel free to submit a pull request with a fix and/or
    15  an update to this paragraph.
    16  
    17  ## Installation
    18  
    19  `$ go get github.com/szmcdull/go-forceexport`
    20  
    21  ## Usage
    22  
    23  Here's how you can grab the `time.now` function, defined as
    24  `func now() (sec int64, nsec int32)`
    25  
    26  ```go
    27  var timeNow func() (int64, int32)
    28  err := forceexport.GetFunc(&timeNow, "time.now")
    29  if err != nil {
    30      // Handle errors if you care about name possibly being invalid.
    31  }
    32  // Calls the actual time.now function.
    33  sec, nsec := timeNow()
    34  ```
    35  
    36  The string you give should be the fully-qualified name. For example, here's
    37  `GetFunc` getting itself.
    38  
    39  ```go
    40  var getFunc func(interface{}, string) error
    41  GetFunc(&getFunc, "github.com/alangpierce/go-forceexport.GetFunc")
    42  ```
    43  
    44  ## The following Go versions are tested:
    45  - 1.18 beta2
    46  - 1.17.5
    47  - 1.16.13
    48  - 1.14.15
    49  
    50  ## Use cases and pitfalls
    51  
    52  This library is most useful for development and hack projects. For example, you
    53  might use it to track down why the standard library isn't behaving as you
    54  expect, or you might use it to try out a standard library function to see if it
    55  works, then later factor the code to be less fragile. You could also try using
    56  it in production; just make sure you're aware of the risks.
    57  
    58  There are lots of things to watch out for and ways to shoot yourself in
    59  the foot:
    60  * If you define the wrong function type, you'll get a function with undefined
    61    behavior that will likely cause a runtime panic. The library makes no attempt
    62    to warn you in this case.
    63  * Calling unexported functions is inherently fragile because the function won't
    64    have any stability guarantees.
    65  * The implementation relies on the details of internal Go data structures, so
    66    later versions of Go might break this library.
    67  * Since the compiler doesn't expect unexported symbols to be used, it might not
    68    create them at all, for example due to inlining or dead code analysis. This
    69    means that functions may not show up like you expect, and new versions of the
    70    compiler may cause functions to suddenly disappear.
    71  * If the function you want to use relies on unexported types, you won't be able
    72    to trivially use it. However, you can sometimes work around this by defining
    73    equivalent copies of those types that you can use, but that approach has its
    74    own set of dangers.
    75  
    76  ## How it works
    77  
    78  The [code](/forceexport.go) is pretty short, so you could just read it, but
    79  here's a friendlier explanation:
    80  
    81  The code uses the `go:linkname` compiler directive to get access to the
    82  `runtime.firstmoduledata` symbol, which is an internal data structure created by
    83  the linker that's used by functions like `runtime.FuncForPC`. (Using
    84  `go:linkname` is an alternate way to access unexported functions/values, but it
    85  has other gotchas and can't be used dynamically.)
    86  
    87  Similar to the implementation of `runtime.FuncForPC`, the code walks the
    88  function definitions until it finds one with a matching name, then gets its code
    89  pointer.
    90  
    91  From there, it creates a function object from the code pointer by calling
    92  `reflect.MakeFunc` and using `unsafe.Pointer` to swap out the function object's
    93  code pointer with the desired one.
    94  
    95  Needless to say, it's a scary hack, but it seems to work!
    96  
    97  ## License
    98  
    99  MIT