From 55b538e87c8137eae7a25171bb78f2345d11176e Mon Sep 17 00:00:00 2001
From: Andinus <andinus@nand.sh>
Date: Wed, 15 Apr 2020 20:04:02 +0530
Subject: Document Pledge functions in readme

The diff is messed up because the order was changed.
---
 README.org | 81 +++++++++++++++++++++++++++++++++++++++++++-------------------
 1 file changed, 57 insertions(+), 24 deletions(-)

diff --git a/README.org b/README.org
index b21bc00..766769f 100644
--- a/README.org
+++ b/README.org
@@ -13,10 +13,10 @@ currently only /OpenBSD/ is supported.
 | GitHub (Mirror) | [[https://github.com/andinus/lynx][Lynx - GitHub]]  |
 
 * Examples
-** Unveil / UnveilStrict
-Unveil takes a path, permission & unveils it, it will return an error if unveil
-fails at any step. "no such file or directory" error is ignored, if you want to
-get that error too then use UnveilStrict.
+** UnveilPaths / UnveilPathsStrict
+UnveilPaths takes a map of path, permission & unveils them one by one, it will
+return an error if unveil fails at any step. "no such file or directory" error
+is ignored, if you want to get that error too then use UnveilPathsStrict.
 
 #+BEGIN_SRC go
 package main
@@ -24,16 +24,20 @@ package main
 import "tildegit.org/andinus/lynx"
 
 func main() {
-	path := "/dev/null"
-	flags := "rw"
+	paths := make(map[string]string)
 
-	err = lynx.Unveil(path, flags)
+	paths["/home"] = "r"
+	paths["/dev/null"] = "rw"
+	paths["/etc/examples"] = "rwc"
+	paths["/root"] = "rwcx"
+
+	err = lynx.UnveilPaths(paths)
 	if err != nil {
 		log.Fatal(err)
 	}
 
 	// This will return an error if the path doesn't exist.
-	err = lynx.UnveilStrict(path, flags)
+	err = lynx.UnveilPathsStrict(paths)
 	if err != nil {
 		log.Fatal(err)
 	}
@@ -60,10 +64,9 @@ func main() {
 	}
 }
 #+END_SRC
-** UnveilPaths / UnveilPathsStrict
-UnveilPaths takes a map of path, permission & unveils them one by one, it will
-return an error if unveil fails at any step. "no such file or directory" error
-is ignored, if you want to get that error too then use UnveilPathsStrict.
+** UnveilBlock
+UnveilBlock is just a wrapper around unix.UnveilBlock, it does nothing extra.
+You should use unix.UnveilBlock.
 
 #+BEGIN_SRC go
 package main
@@ -71,28 +74,42 @@ package main
 import "tildegit.org/andinus/lynx"
 
 func main() {
-	paths := make(map[string]string)
+	// Block further unveil calls.
+	err = lynx.UnveilBlock()
+	if err != nil {
+		log.Fatal(err)
+	}
+}
+#+END_SRC
+** Unveil / UnveilStrict
+Unveil takes a path, permission & unveils it, it will return an error if unveil
+fails at any step. "no such file or directory" error is ignored, if you want to
+get that error too then use UnveilStrict.
 
-	paths["/home"] = "r"
-	paths["/dev/null"] = "rw"
-	paths["/etc/examples"] = "rwc"
-	paths["/root"] = "rwcx"
+#+BEGIN_SRC go
+package main
 
-	err = lynx.UnveilPaths(paths)
+import "tildegit.org/andinus/lynx"
+
+func main() {
+	path := "/dev/null"
+	flags := "rw"
+
+	err = lynx.Unveil(path, flags)
 	if err != nil {
 		log.Fatal(err)
 	}
 
 	// This will return an error if the path doesn't exist.
-	err = lynx.UnveilPathsStrict(paths)
+	err = lynx.UnveilStrict(path, flags)
 	if err != nil {
 		log.Fatal(err)
 	}
 }
 #+END_SRC
-** UnveilBlock
-UnveilBlock is just a wrapper around unix.UnveilBlock, it does nothing extra.
-You should use unix.UnveilBlock.
+** Pledge / PledgePromises / PledgeExecpromises
+These are simple wrappers to unix package functions. They add nothing extra, you
+could simply change lynx.Pledge to unix.Pledge & it would just work.
 
 #+BEGIN_SRC go
 package main
@@ -100,8 +117,24 @@ package main
 import "tildegit.org/andinus/lynx"
 
 func main() {
-	// Block further unveil calls.
-	err = lynx.UnveilBlock()
+	promises := "stdio unveil"
+	execpromises := "stdio"
+
+	err = lynx.Pledge(promises, execpromises)
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	// Drop promises.
+	promises = "stdio"
+	err = lynx.PledgePromises(promises)
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	// Drop execpromises.
+	execpromises = ""
+	err = lynx.PledgeExecpromises(execpromises)
 	if err != nil {
 		log.Fatal(err)
 	}
-- 
cgit 1.4.1-2-gfad0