Add utility to return the effective user identity

kgryte · kgryte · commit ba605405d862 · 2018-01-26T13:38:09.000-08:00
diff --git a/lib/node_modules/@stdlib/process/geteuid/README.md b/lib/node_modules/@stdlib/process/geteuid/README.md
@@ -0,0 +1,61 @@
+# geteuid
+
+> Return the effective numeric user identity of the calling process.
+
+<section class="usage">
+
+## Usage
+
+```javascript
+var geteuid = require( '@stdlib/process/geteuid' );
+```
+
+#### geteuid()
+
+Returns the effective numeric user identity of the calling process.
+
+```javascript
+var id = geteuid();
+```
+
+</section>
+
+<!-- /.usage -->
+
+<section class="notes">
+
+## Notes
+
+-   The function **only** returns an `integer` user identity on POSIX platforms. For all other platforms (e.g., Windows and Android), the function returns `null`. 
+-   See [geteuid(2)][geteuid].
+
+</section>
+
+<section class="examples">
+
+## Examples
+
+<!-- eslint no-undef: "error" -->
+
+```javascript
+var geteuid = require( '@stdlib/process/geteuid' );
+
+var uid = geteuid();
+if ( uid === 0 ) {
+    console.log( 'Effectively running as root.' );
+} else {
+    console.log( 'uid: %d', uid );
+}
+```
+
+</section>
+
+<!-- /.examples -->
+
+<section class="links">
+
+[geteuid]: http://man7.org/linux/man-pages/man2/geteuid.2.html
+
+</section>
+
+<!-- /.links -->
diff --git a/lib/node_modules/@stdlib/process/geteuid/benchmark/benchmark.browser.js b/lib/node_modules/@stdlib/process/geteuid/benchmark/benchmark.browser.js
@@ -0,0 +1,31 @@
+'use strict';
+
+// MODULES //
+
+var bench = require( '@stdlib/bench' );
+var isNull = require( '@stdlib/assert/is-null' );
+var pkg = require( './../package.json' ).name;
+var geteuid = require( './../lib/polyfill.js' );
+
+
+// MAIN //
+
+bench( pkg+'::browser', function benchmark( b ) {
+	var uid;
+	var i;
+
+	b.tic();
+	for ( i = 0; i < b.iterations; i++ ) {
+		// Note: the following *could* be optimized away via loop-invariant code motion. If so, the entire loop will disappear.
+		uid = geteuid();
+		if ( !isNull( uid ) ) {
+			b.fail( 'should return null' );
+		}
+	}
+	b.toc();
+	if ( !isNull( uid ) ) {
+		b.fail( 'should return null' );
+	}
+	b.pass( 'benchmark finished' );
+	b.end();
+});
diff --git a/lib/node_modules/@stdlib/process/geteuid/benchmark/benchmark.js b/lib/node_modules/@stdlib/process/geteuid/benchmark/benchmark.js
@@ -0,0 +1,32 @@
+'use strict';
+
+// MODULES //
+
+var bench = require( '@stdlib/bench' );
+var isNumber = require( '@stdlib/assert/is-number' ).isPrimitive;
+var isNull = require( '@stdlib/assert/is-null' );
+var pkg = require( './../package.json' ).name;
+var geteuid = require( './../lib' );
+
+
+// MAIN //
+
+bench( pkg, function benchmark( b ) {
+	var uid;
+	var i;
+
+	b.tic();
+	for ( i = 0; i < b.iterations; i++ ) {
+		// Note: the following *could* be optimized away via loop-invariant code motion. If so, the entire loop will disappear.
+		uid = geteuid();
+		if ( !isNumber( uid ) && !isNull( uid ) ) {
+			b.fail( 'should return a number or null' );
+		}
+	}
+	b.toc();
+	if ( !isNumber( uid ) && !isNull( uid ) ) {
+		b.fail( 'should return a number or null' );
+	}
+	b.pass( 'benchmark finished' );
+	b.end();
+});
diff --git a/lib/node_modules/@stdlib/process/geteuid/docs/repl.txt b/lib/node_modules/@stdlib/process/geteuid/docs/repl.txt
@@ -0,0 +1,19 @@
+
+{{alias}}()
+    Returns the effective numeric user identity of the calling process.
+
+    The function only returns a user identity on POSIX platforms. For all other
+    platforms (e.g., Windows and Android), the function returns `null`.
+
+    Returns
+    -------
+    id: integer|null
+        Effective numeric user identity.
+
+    Examples
+    --------
+    > var uid = {{alias}}()
+
+    See Also
+    --------
+
diff --git a/lib/node_modules/@stdlib/process/geteuid/examples/index.js b/lib/node_modules/@stdlib/process/geteuid/examples/index.js
@@ -0,0 +1,10 @@
+'use strict';
+
+var geteuid = require( './../lib' );
+
+var uid = geteuid();
+if ( uid === 0 ) {
+	console.log( 'Effectively running as root.' );
+} else {
+	console.log( 'uid: %d', uid );
+}
diff --git a/lib/node_modules/@stdlib/process/geteuid/lib/index.js b/lib/node_modules/@stdlib/process/geteuid/lib/index.js
@@ -0,0 +1,21 @@
+'use strict';
+
+/**
+* Return the effective numeric user identity of the calling process.
+*
+* @module @stdlib/process/geteuid
+*
+* @example
+* var geteuid = require( '@stdlib/process/geteuid' );
+*
+* var uid = geteuid();
+*/
+
+// MODULES //
+
+var geteuid = require( './main.js' );
+
+
+// EXPORTS //
+
+module.exports = geteuid;
diff --git a/lib/node_modules/@stdlib/process/geteuid/lib/main.js b/lib/node_modules/@stdlib/process/geteuid/lib/main.js
@@ -0,0 +1,27 @@
+'use strict';
+
+// MODULES //
+
+var isFunction = require( '@stdlib/assert/is-function' );
+var polyfill = require( './polyfill.js' );
+var builtin = require( './native.js' );
+
+
+// MAIN //
+
+/**
+* Returns the effective numeric user identity of the calling process.
+*
+* @name geteuid
+* @type {Function}
+* @returns {(integer|null)} effective numeric user identity or null
+*
+* @example
+* var uid = geteuid();
+*/
+var geteuid = ( isFunction( builtin ) ) ? builtin : polyfill;
+
+
+// EXPORTS //
+
+module.exports = geteuid;
diff --git a/lib/node_modules/@stdlib/process/geteuid/lib/native.js b/lib/node_modules/@stdlib/process/geteuid/lib/native.js
@@ -0,0 +1,19 @@
+'use strict';
+
+/**
+* Returns the effective numeric user identity of the calling process.
+*
+* @private
+* @name geteuid
+* @type {Function}
+* @returns {integer} effective numeric user identity
+*
+* @example
+* var uid = geteuid();
+*/
+var geteuid = process.geteuid;
+
+
+// EXPORTS //
+
+module.exports = geteuid;
diff --git a/lib/node_modules/@stdlib/process/geteuid/lib/polyfill.js b/lib/node_modules/@stdlib/process/geteuid/lib/polyfill.js
@@ -0,0 +1,24 @@
+'use strict';
+
+// MAIN //
+
+/**
+* Polyfill for returning an effective numeric user identity for environments which do not provide native support.
+*
+* @private
+* @name geteuid
+* @type {Function}
+* @returns {null} null
+*
+* @example
+* var uid = geteuid();
+* // returns null
+*/
+function geteuid() {
+	return null;
+}
+
+
+// EXPORTS //
+
+module.exports = geteuid;
diff --git a/lib/node_modules/@stdlib/process/geteuid/package.json b/lib/node_modules/@stdlib/process/geteuid/package.json
@@ -0,0 +1,71 @@
+{
+  "name": "@stdlib/process/geteuid",
+  "version": "0.0.0",
+  "description": "Return the effective numeric user identity of a calling process.",
+  "license": "Apache-2.0",
+  "author": {
+    "name": "The Stdlib Authors",
+    "url": "https://github.com/stdlib-js/stdlib/graphs/contributors"
+  },
+  "contributors": [
+    {
+      "name": "The Stdlib Authors",
+      "url": "https://github.com/stdlib-js/stdlib/graphs/contributors"
+    }
+  ],
+  "main": "./lib",
+  "browser": "./lib/polyfill.js",
+  "directories": {
+    "benchmark": "./benchmark",
+    "doc": "./docs",
+    "example": "./examples",
+    "lib": "./lib",
+    "test": "./test"
+  },
+  "scripts": {},
+  "homepage": "https://github.com/stdlib-js/stdlib",
+  "repository": {
+    "type": "git",
+    "url": "git://github.com/stdlib-js/stdlib.git"
+  },
+  "bugs": {
+    "url": "https://github.com/stdlib-js/stdlib/issues"
+  },
+  "dependencies": {},
+  "devDependencies": {},
+  "engines": {
+    "node": ">=0.10.0",
+    "npm": ">2.7.0"
+  },
+  "os": [
+    "aix",
+    "darwin",
+    "freebsd",
+    "linux",
+    "macos",
+    "openbsd",
+    "sunos",
+    "win32",
+    "windows"
+  ],
+  "keywords": [
+    "stdlib",
+    "stdutils",
+    "stdutil",
+    "utils",
+    "util",
+    "utilities",
+    "utility",
+    "process",
+    "geteuid",
+    "getuid",
+    "posix",
+    "linux",
+    "darwin",
+    "effective",
+    "uid",
+    "user",
+    "identity",
+    "id"
+  ]
+}
diff --git a/lib/node_modules/@stdlib/process/geteuid/test/test.js b/lib/node_modules/@stdlib/process/geteuid/test/test.js
@@ -0,0 +1,52 @@
+'use strict';
+
+// MODULES //
+
+var tape = require( 'tape' );
+var proxyquire = require( 'proxyquire' );
+var IS_BROWSER = require( '@stdlib/assert/is-browser' );
+var geteuid = require( './../lib' );
+
+
+// VARIABLES //
+
+var opts = {
+	'skip': IS_BROWSER
+};
+
+
+// TESTS //
+
+tape( 'main export is a function', opts, function test( t ) {
+	t.ok( true, __filename );
+	t.strictEqual( typeof geteuid, 'function', 'main export is a function' );
+	t.end();
+});
+
+tape( 'if `process.geteuid` is a function, the main export aliases `process.geteuid`', opts, function test( t ) {
+	var geteuid = proxyquire( './../lib/main.js', {
+		'@stdlib/assert/is-function': isFunction
+	});
+	t.strictEqual( geteuid, process.geteuid, 'is alias' );
+	t.end();
+
+	function isFunction() {
+		return true;
+	}
+});
+
+tape( 'if an environment does not support `process.geteuid`, the main export always returns `null`', opts, function test( t ) {
+	var geteuid = proxyquire( './../lib/main.js', {
+		'@stdlib/assert/is-function': isFunction
+	});
+	t.strictEqual( typeof geteuid, 'function', 'main export is a function' );
+	t.strictEqual( geteuid(), null, 'returns null' );
+	t.strictEqual( geteuid(), null, 'returns null' );
+	t.strictEqual( geteuid(), null, 'returns null' );
+	t.strictEqual( geteuid(), null, 'returns null' );
+	t.end();
+
+	function isFunction() {
+		return false;
+	}
+});
diff --git a/lib/node_modules/@stdlib/process/geteuid/test/test.polyfill.js b/lib/node_modules/@stdlib/process/geteuid/test/test.polyfill.js
